> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connectors
> Browse, add, and manage connectors in Runlayer
## What a Connector Is
A connector is a managed MCP server in Runlayer. It packages the MCP endpoint together with auth, configuration, permissions, and client setup instructions so your team can use it from any AI client.
Key parts:
* **Tools**: Actions the MCP can perform (e.g., "create issue", "search code")
* **Resources**: Data the MCP can access (e.g., repository files, issues)
* **Status**:
* `Active` — Ready to use
* `Disabled` — Turned off or not yet configured
* `Draft` — Only visible to the creator; hidden from other users, the MCP endpoint, and the proxy until the connector is activated
Connector *requests* (when a team member asks an admin to add a connector) have their own statuses: `Pending`, `Approved`, and `Rejected`.
There are three ways to add connectors to Runlayer: from the **connector catalog**, **manually**, or via **Runlayer Deploy**.
***
## The Connector Catalog
The connector catalog is Runlayer's curated registry of pre-validated MCP server templates. When you open **My connectors**, the catalog is what powers the list of connectors your team can browse and request.
### What you get from catalog connectors
* **Validated to work** — Runlayer has tested each catalog connector to confirm it works correctly
* **ToolGuard security scans** — Each connector's tools have been statically scanned for security risks. You can review scan results before enabling a connector.
* **Pre-filled configuration** — Selecting a catalog connector pre-fills the setup form with the correct transport type, auth method, environment variables, and defaults. No guesswork.
### How it works
Catalog entries are templates — they don't become connectors until someone adds or requests them.
**For admins:**
1. Open **My connectors** in the left sidebar
2. Use search or the **All / Hosted / Local** tabs to find a connector
3. Open any connector card to review its tools, description, and security scan results
4. Click **Add connector** to create a connector from the template
5. Complete any remaining setup (auth, environment variables) and save
**For team members:**
1. Browse **My connectors** the same way
2. Click **Request new** on the connector they need
3. Enter a reason for the request
4. An admin reviews and approves or rejects the request
Admins manage requests from the **Manage connectors** view.
### What happens after a request
1. **Pending** — The request appears with `Pending` status. You can see your own pending requests on **My connectors**. Admins are notified by email and, if configured, in a Slack channel.
2. **Approved** — The admin sets up the connector (auth, configuration) as part of approving. The request status changes to `Approved`, you're notified via Slack DM, and the connector becomes available to connect from your AI clients. No further action is needed beyond connecting it in your client.
3. **Rejected** — The request status changes to `Rejected` and you're notified via Slack DM, including the rejection reason if the admin provided one. Talk to your admin if you believe the connector should be reconsidered.
Every decision is recorded in the [audit log](/platform-audit-logs). See [Approvals](/platform-approvals) for the admin side of this workflow.
### Full catalog list
The catalog is continuously growing. To request the full list of available connectors, ask your account representative.
A snapshot of what's covered today:
* **Built and maintained by Runlayer** — connectors with dedicated setup guides: [Adaptive](/servers/adaptive), [Gong](/servers/gong), [Google Workspace](/servers/google-workspace), [Metabase](/servers/metabase), [Microsoft 365](/servers/microsoft-365) (Outlook, OneDrive, SharePoint, Calendar, Teams), [Slack](/servers/slack), and [Snowflake](/servers/snowflake)
* **Official vendor MCPs** — servers maintained by the upstream SaaS provider (e.g., GitHub, Asana, Ramp, Datadog, Microsoft Agent 365), many connected through the [OAuth Broker](/oauth-broker)
* **New connectors ship regularly** — see the [changelog](/changelog) for recent additions
Runlayer doesn't limit you to the catalog: any MCP server can be [added manually](#adding-a-connector-manually).
### Runlayer-built vs. vendor-native vs. custom
Connector pages and catalog entries can represent several ownership models:
| Model | What it means | Examples |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
| **Runlayer-built** | Runlayer maintains the MCP server implementation and setup guide. Traffic runs through Runlayer for auth, policy, scanning, audit, and analytics. | Google Workspace, Microsoft 365, Snowflake |
| **Official vendor MCP** | The upstream SaaS vendor maintains the MCP server. Runlayer connects users to it through the gateway, often through the [OAuth Broker](/oauth-broker). | GitHub, Asana, Ramp, Datadog, Microsoft Agent 365 |
| **Manual/custom** | Your team points Runlayer at an internal, community, or proprietary MCP endpoint. Admins own review and configuration. | Internal APIs, private databases, custom support tools |
| **Local** | The MCP server runs on the user's machine behind the Runlayer CLI. Runlayer still applies policy and audit at the proxy boundary. | Filesystem, shell, local databases |
Vendor-native connectors inside Claude, ChatGPT, or another client can coexist with Runlayer, but Runlayer can only enforce policies, ToolGuard, and audit logs on traffic that goes through Runlayer or a supported endpoint hook.
### Catalog connector types
| Type | Description | Examples |
| ---------- | -------------------------------------------------- | ------------------------------------------- |
| **Hosted** | Connects to external cloud services via API | Slack, GitHub, Salesforce, Google Workspace |
| **Local** | Operates on the user's local machine or filesystem | Filesystem, shell, local databases |
Some hosted connectors are **Runlayer-managed** — Runlayer hosts and runs the MCP server infrastructure for you.
For details on local execution, proxying, setup, and local secrets, see [Local MCPs](/local-mcps).
***
## Adding a Connector Manually
If the MCP server you need isn't in the catalog, admins can add it directly using the **Create New** button. This bypasses the catalog entirely and lets you point Runlayer at any MCP endpoint.
### When to use this
* **Internal or proprietary MCP servers** — Built by your team for internal use
* **Community or unofficial MCP servers** — The catalog only includes servers officially maintained by the upstream SaaS provider. Community-built or third-party servers should be added manually.
* **Existing MCP endpoints** — You already have an MCP server running and want to manage it through Runlayer
If your manually added connector requires IP allowlisting, open **Settings →
Network Access** and allowlist the tenant-specific outbound IPv4 addresses and
IPv6 ranges shown there. For other special networking requirements, such as
VPN or private subnets, contact Runlayer to configure connectivity.
**Does Runlayer need direct access to my private apps?** Only for HTTP-based connectors whose upstream MCP endpoint is private — in that case, allowlist Runlayer's outbound IPs (shown in **Settings → Network Access**) in your firewall, or contact Runlayer for VPN/private-subnet connectivity. [Local MCPs](/local-mcps) run on the user's machine behind the Runlayer CLI, so Runlayer doesn't need inbound network access to the user's machine or the systems the local MCP reaches.
### How to add a connector manually
From **My connectors** or **Manage connectors**, click **Add connector**, then click **Create New** to skip the catalog and go straight to the configuration form.
Fill in the required fields:
* **Icon** — Pick a custom icon for the connector (optional; only for custom connectors — catalog connectors use their predefined icon)
* **Name** — Display name for the connector
* **URL or Command** — The MCP endpoint URL (e.g., `https://mcp.example.com/mcp`) or a command for STDIO servers. For hosted STDIO, use `npx`, `uvx`, or `uv`; for local STDIO, any local binary command is allowed.
* **Transport type** — Streaming HTTP (default), SSE, or STDIO
For HTTP-based transports, choose an auth method:
* **Auto** — Runlayer auto-detects the auth mechanism (default)
* **OAuth 2.1** — Configure OAuth with Client ID Metadata Document or Dynamic Client Registration, pre-registered credentials, or the [OAuth Broker](/oauth-broker)
* **Bearer Token** — Static token-based auth
* **None** — No authentication required
For STDIO transports, configure **arguments** and **environment variables** instead.
Expand **Advanced settings** to configure:
* **Description** — What the connector does
* **Tool output offloading** — Prevents context bloat from large tool outputs (enabled by default)
* **Skip tool input validation** — Bypass strict MCP input schema validation for servers with malformed schemas; disables server-scoped payload-based PBAC conditions
* **Sensitive connector** — Redacts audit log entries and restricts visibility to selected roles
* **Identity Forward** — Inject the authenticated caller's identity into upstream requests via plain headers or a signed JWT. See [Deploy — Identity Forward](/platform-deploy#identity-forward) for the full reference. Available on any HTTP-based connector (Streaming HTTP or SSE), not just deployed servers.
Click **Create** to add the connector. It's now available in your workspace and can be assigned to users, have policies applied, and be connected to AI clients.
Headers for HTTP connectors support **placeholder syntax** (e.g., `{"{API_KEY}"}`) so each user can provide their own credentials at connection time.
***
## Deploying a Custom Connector
For MCP servers you build yourself, **Runlayer Deploy** lets you deploy them to managed infrastructure and register them as connectors — all from the CLI.
### When to use this
* You're building a custom MCP server for your team
* You need managed infrastructure (auto-scaling, HTTPS, monitoring)
* You want the full lifecycle: build, deploy, register, manage
### How it works
```bash theme={null}
uvx runlayer login --host
uvx runlayer deploy init --host
```
This creates a deployment and generates a `runlayer.yaml` config file.
Edit `runlayer.yaml` with your service port, resources, and environment variables, then deploy:
```bash theme={null}
uvx runlayer deploy --host
```
Runlayer builds your Docker image, pushes it, and deploys it to managed infrastructure.
After deployment succeeds, open the deployment detail page in the Runlayer UI and click **Register as MCP Server**. Your deployed service is now a connector — browsable, assignable, and policy-enforced like any other connector.
For the full configuration reference, CLI commands, and examples, see the [Deploy documentation](/platform-deploy).
***
## Will an arbitrary MCP server work?
Any MCP server can be [added manually](#adding-a-connector-manually), but "can be added" and "works end-to-end today" are not the same thing. A catalog entry is Runlayer's signal that **we have tested that server end-to-end and confirmed it works** through the gateway. Servers you add yourself have not been through that validation, so a small number hit one of the issues below before they connect cleanly.
When you're scoping a POC, [inventory the MCP servers your team already uses in Claude, ChatGPT, and Cursor early](#scope-connectors-early) — a few of them can take days or weeks to clear, and you want that clock started before the POC, not during it.
### Three things that decide whether a server connects
Some servers deviate from the MCP specification. Like other MCP clients (Claude, ChatGPT, Cursor), Runlayer tolerates common deviations, and the manual **Create New** setup form exposes options to work around them — for example, adjusting transport type or auth handling — so you rarely need the vendor to change their code. If a server fails to connect and you suspect a spec quirk, contact your Runlayer account team; we can usually add a compatibility option.
Many hosted MCP servers only accept connections from a short list of named clients (commonly Claude, ChatGPT, and Cursor) and reject everything else. When the server you want does this, the vendor has to **allowlist Runlayer as an approved MCP client** before it will connect. Runlayer handles this outreach, but it depends on the vendor's timeline — most agree quickly, some take longer.
A related case: a few servers aren't publicly advertised as connectable at all (for example, Google Workspace, where Anthropic has a special arrangement). For those, Runlayer's fallback is to build and host an equivalent server on [Runlayer Deploy](/platform-deploy).
Because vendor allowlisting is outside Runlayer's control, treat any *un-cataloged, client-restricted* server as a potential multi-week item and raise it before the POC starts.
Most servers fall here. Occasionally there's one-time admin setup on the vendor side — flipping a "allow all MCP clients" setting, or pasting Runlayer's [OAuth redirect URIs](#oauth-redirect-uri-controls) into the vendor's app registration. When a Runlayer-built or catalog connector needs this, the setup guide links the exact place to do it.
### Not in the catalog yet?
Missing from the catalog is not a blocker on its own. You can:
* **Add it as a custom connector now** with [Create New](#adding-a-connector-manually) and point Runlayer at the endpoint. If the server is client-restricted (case 2 above), ask your account team to start vendor allowlisting in parallel.
* **Request catalog coverage** so Runlayer validates it end-to-end and pre-fills its configuration for everyone — ask your account representative.
Custom and catalog connectors are governed identically once connected: the same policies, ToolGuard scanning, and audit logging apply regardless of how the connector was added.
### Scope connectors early
Before a POC, ask the customer for the full list of MCP servers they have configured in Claude and ChatGPT. Map each to one of:
| Status | Meaning | Action |
| ------------------------------------- | ------------------------- | ------------------------------------------------- |
| **In catalog** | Validated end-to-end | Add or request — no lead time |
| **Not in catalog, spec-compliant** | Works via Create New | Add manually |
| **Not in catalog, client-restricted** | Needs vendor allowlisting | Flag to account team immediately — can take weeks |
| **Not publicly connectable** | No open MCP endpoint | Rebuild on Runlayer Deploy as a last resort |
This turns surprises during the POC into known, tracked items up front.
***
## Using connectors in an AI client
Open a connector and click **Add to Client**. If the connector is already included in [Runlayer Plugin](/runlayer-plugin), Runlayer recommends that shared connection first. Click **Connect** to use Runlayer Plugin, or continue with the client-specific instructions to add the connector directly.
To work with several connectors at once:
1. Open **My connectors** and select the connector cards.
2. Click **Add to Client** in the selection bar.
3. Use Runlayer Plugin, add the connectors to an editable Plugin, or create a new Plugin.
Only active hosted connectors can be selected for a Plugin. Local, draft, and disabled connectors still use their existing setup paths. See [Plugins](/platform-plugins#creating-or-extending-a-plugin) for the complete flow.
***
## Security
All connectors — regardless of how they're added — are protected by [Runlayer ToolGuard](/runlayer-toolguard). ToolGuard is a suite of ML models that detect tool poisoning, prompt injection, and data exfiltration in real time.
### How ToolGuard applies to each flow
**Tool List Guard** scans tool *definitions* (names, descriptions, parameters) to detect hidden instructions, prompt injection, and risky patterns before tools are made available:
* **Catalog connectors** are pre-scanned by Runlayer before being published to the catalog. Scan results are visible on each connector card so you can review them before enabling.
* **Manual and deployed connectors** are scanned by Tool List Guard when they're registered. You'll see the same scan results, but Runlayer hasn't pre-reviewed them — it's on the admin to review before enabling.
**Tool Call Guard** scans tool *outputs* at runtime to detect data exfiltration, prompt injection in responses, and command injection before results reach the LLM. This applies to **all connectors** equally, regardless of how they were added.
**Tool Intent Guard** analyzes tool inputs and outputs *together* to detect semantic misalignment — cases where a tool's behavior diverges from what was requested (e.g., a "read file" tool that silently exfiltrates data). This also applies to **all connectors** at runtime.
| | Catalog | Manual | Deploy |
| --------------------- | ------------------------------------ | -------------------------------------- | -------------------------------------- |
| **Tool List Guard** | Pre-scanned and reviewed by Runlayer | Scanned at registration, admin reviews | Scanned at registration, admin reviews |
| **Tool Call Guard** | Yes, at runtime | Yes, at runtime | Yes, at runtime |
| **Tool Intent Guard** | Yes, at runtime | Yes, at runtime | Yes, at runtime |
ToolGuard sensitivity can be configured globally in **Settings → Security Scanners**, overridden per connector, or set per client. See [ToolGuard Models](/runlayer-toolguard) for details.
***
## OAuth Redirect URI Controls
When a connector uses OAuth, the AI client sends the user to the provider's login page and asks it to deliver the resulting authorization code to a **redirect URI** (also called a callback URL). That redirect URI is where the short-lived code — and ultimately the access token to your data — lands.
### Why a malicious redirect URI is dangerous
A redirect URI is a high-value target. If an attacker can get a connector to redirect to a URI they control, the OAuth flow hands them the authorization code, which they exchange for a live access token — no password or MFA prompt required. Common attacks include:
* **Authorization-code interception** — a look-alike or attacker-owned callback (e.g. `https://app.evil.com/oauth/callback`) silently captures codes mid-flow.
* **Open-redirect chaining** — a trusted host with an open redirect is abused to bounce the code on to an attacker.
* **Consent phishing** — users are walked through a real-looking consent screen that quietly points at the wrong destination.
Because the token grants the same access the user has, a single bad redirect URI can lead to data exfiltration that never trips a login or MFA challenge.
### How Runlayer enforces redirect URIs
Admins control which redirect URIs OAuth clients may use under **Settings → General → OAuth redirect URIs**:
* **Allowed redirect URIs** — trusted URIs that connect with no extra prompt.
* **Blocked redirect URIs** — URIs blocked org-wide.
* Entries support exact URIs and wildcard host patterns (e.g. `https://*.example.com/cb`).
Behavior at connect time:
* A redirect URI on the **allowlist** proceeds normally.
* A redirect URI on the **denylist** is blocked. **Blocking always wins over allowing.**
* A redirect URI that matches **neither** list pauses the flow and asks an admin to approve it before anyone in the org can use it.
Every block and approval is recorded in the [audit log](/platform-audit-logs).
**Recipe: trust local (loopback) clients in one shot.** Many CLI and local dev
MCP clients receive their callback on a loopback address with a random port,
per [RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3). To
allow them without an approval prompt on every new port, add the loopback hosts
with a trailing path wildcard to **Allowed redirect URIs**:
```
http://localhost/*
http://127.0.0.1/*
http://[::1]/*
```
Loopback matches ignore the port, so each entry covers any ephemeral port the
client picks. `http` is permitted **only** for these loopback hosts — never for
remote hosts — so this does not weaken protection against external redirect
URIs.
Some clients instead use a custom-scheme deep link (a "magic link") rather than
a loopback callback — for example Cursor uses
`cursor://anysphere.cursor-mcp/oauth/callback`. Allowlist that exact URI as-is;
the loopback patterns above do not cover it.
### What to do if a redirect URI is blocked
If you saw **"This redirect URI is blocked for your organization"** while connecting a client, the callback URL your AI client tried to use is on your organization's blocked list. This is a safety control, not a bug — it stops OAuth tokens from being handed to an untrusted destination.
What to do:
1. Confirm you're connecting an approved, official client — not a fork or a tool from an untrusted source.
2. Share the connector and the client you're using with your Runlayer admin.
3. An admin can review the redirect URI under **Settings → General → OAuth redirect URIs** and, if it's legitimate, add it to the allowed list.
Admins: only allow redirect URIs you recognize and trust. Adding a URI here tells Runlayer to hand OAuth tokens to that destination for everyone in your org. When in doubt, leave it blocked.
***
## Comparison
| | Catalog | Manual | Deploy |
| -------------------------------- | ------------------------------------ | ------------------------------------ | ------------------------ |
| **Setup effort** | Pre-filled form | Fill in form | CLI + Dockerfile |
| **Pre-scanned by Runlayer** | Yes | No | No |
| **Runtime security (ToolGuard)** | Yes | Yes | Yes |
| **Validated to work** | Yes | No | No |
| **Runs on Runlayer infra** | Hosted STDIO connectors | Hosted STDIO connectors | All deployed connectors |
| **User installs anything?** | Only local connectors (Runlayer CLI) | Only local connectors (Runlayer CLI) | No |
| **Policy enforcement** | Yes | Yes | Yes |
| **Best for** | Standard integrations | Existing MCP endpoints | Custom-built MCP servers |
Any **hosted STDIO** connector — whether from the catalog or created manually — automatically runs on Runlayer infrastructure. HTTP-based connectors (Streaming HTTP, SSE) connect to an upstream URL, unless you use Runlayer Deploy to host the server yourself. **Local** connectors are the exception: they run on the user's machine and require the [Runlayer CLI](/local-mcps) to be installed there.
***
## Managing Connectors
Admins have a separate **Manage connectors** view for workspace-wide inventory, approvals, and permissions.
From **Manage connectors**, admins can:
* View all connectors across the workspace
* Approve or reject connector requests from users
* Edit connector settings, including auth configuration
* Disable or re-enable connectors
* Apply [policies](/platform-policies) to control tool access
* Monitor connector status and usage via [analytics](/platform-analytics) and [audit logs](/platform-audit-logs)
### Editing connector settings
Admins can edit an existing connector's configuration — including authentication method, OAuth settings, headers, and environment variables — from the **Settings** tab on the connector's detail page (**Manage connectors → \[connector] → Settings**). This is the same form used when creating the connector, so anything set at creation time can be changed later.
If a connector's credentials change or expire, individual users may also need to revoke and reconnect their own authorization — see [Troubleshooting: Revoke and Reconnect App Authentication](/mcp-troubleshooting#fix-3-revoke-and-reconnect-app-authentication).
### Disabling and re-enabling connectors
Admins can disable any connector from its detail page (**Disable server** in the actions menu) or as a one-click remediation from [Incidents](/platform-incidents). Disabling sets the connector's status to `Disabled`, making it inaccessible workspace-wide until an admin re-enables it from the same menu. Both actions are recorded in the [audit log](/platform-audit-logs) (`server_disabled` / `server_enabled` events, including who acted and the disable reason).
### Searching connectors
Connectors can be searched by name or description in two ways:
* **Command palette** — press **Cmd/Ctrl+K** from anywhere in the app and type a connector name
* **API** — use the `query` parameter on the servers API to filter connectors server-side
***
## FAQ
**How often do users need to reauthorize a connector?**
There's no fixed cadence. For OAuth connectors, tokens are refreshed automatically where the vendor supports it, so users typically authorize once and stay connected until the token is revoked or the vendor's refresh expires. Lifetimes vary by vendor — for example, Salesforce access tokens last about 2 hours but refresh automatically when the `refresh_token` scope is enabled. When automatic refresh isn't possible (token expired, revoked, or scopes changed), users see auth errors like `401 Unauthorized` and need to revoke and reconnect — see [Troubleshooting](/mcp-troubleshooting#fix-3-revoke-and-reconnect-app-authentication). Many AI clients prompt for re-authentication automatically in that case.
***
## Related Resources
Get your first connector working in a client
Deploy custom MCP servers to managed infrastructure
Control tool access with policies