Remote MCP servers

A remote MCP server is an MCP server that a third party already runs. The Control Plane registers its URL and proxies whole MCP sessions to it, so nothing is copied, rebuilt, or re-hosted. The upstream keeps serving its own tools, and the Control Plane adds authentication, per-tool access control, usage metering, and tool logs in front.

The only supported transport is streamable HTTP. The create form shows the transport as fixed, and catalog installs skip endpoints that use anything else.

There are two ways to register one: by URL, or from the catalog.

Adding a server by URL

Open Connect > Sources and choose Add a custom remote MCP server. The form takes a display name, the server URL, and nothing else. Adding a server requires the mcp:write scope.

Verify probes the URL before the server is created.

Verify checks reachability, not credentials. An upstream that answers with 401 or 403 still counts as verified, reported as “Reachable: received authorization required response”. A verified URL means the endpoint exists and responds, not that the server is configured to call it successfully.

Adding the server does four things in sequence: it registers the remote server record, links an MCP server config to it, tries to configure authentication automatically, and pre-stages a default MCP endpoint. A failure partway through rolls the record back, so a half-created server does not linger.

Automatic authentication setup

When the upstream advertises OAuth protected-resource metadata and its authorization server supports dynamic client registration, the Control Plane registers a client with that authorization server and attaches it to the new server. The success toast reads “Remote MCP server added and authentication configured”, and the server’s visibility moves from disabled to private, so it is immediately usable by authenticated callers.

When any step does not apply, the server is still created and a warning names the reason. The common ones:

• The upstream publishes no OAuth protected-resource metadata, so there is nothing to configure.
• The upstream publishes metadata but its authorization server has no registration endpoint, so dynamic client registration is unavailable. Servers in this state need manual credentials.
• A matching identity provider already exists but is missing its authorization or token endpoint.

Anything not configured automatically can be set up from the Authentication section of the server’s Settings tab. See Upstream credentials.

Adding a server from the catalog

The MCP Catalog page lists third-party MCP servers from a public registry, crawled and cached by the Control Plane. Browse or search, open a server for its description, tool list, usage estimates, and version history, then click Add.

Reaching the catalog requires the project:read and mcp:write scopes.

A few properties of the catalog are worth knowing before relying on it:

• The catalog holds roughly 100 servers, not the whole public registry. Search, sort, and filter all run over that cached list in the browser.
• A Manual Setup badge means the server’s authorization server exposes no registration endpoint. Connecting to it needs static OAuth client credentials or an API key, set up by hand. The badge is derived from the authorization server’s own metadata rather than from what the registry claims.
• Only the first five remote endpoints of a catalog entry are inspected.

One entry can create several servers

A catalog entry can publish more than one remote endpoint. The install dialog lists them and creates one MCP server per selected endpoint, after discarding non-streamable-HTTP endpoints and deduplicating by normalized URL. A vendor that publishes separate endpoints per product line produces separate servers, each with its own URL, auth, and access rules.

Installing an entry that is already in the project is allowed. It creates another server rather than editing the existing one; the “already in this project” marker is informational.

Upstream headers

The configure step of the install dialog collects upstream headers, with the help text “Values are stored on the server and sent with every upstream request.” Header values are encrypted at rest. This step can be skipped, and headers can be added later from the server’s Settings tab.

Authorization is never collected here. On servers that support dynamic client registration, automatic auth setup owns it; everywhere else it belongs in the server’s authentication settings.

How the two paths differ

	By URL	From the catalog
Entry point	Connect > Sources	MCP Catalog
URL	Typed by hand	Taken from the registry entry, deduplicated
Servers created	One	One per selected endpoint
Upstream headers	Added afterwards in Settings	Collected during install
Initial visibility	Disabled	Private

The visibility difference is deliberate. A catalog install promises a server that works right away, so its pre-staged endpoint has to serve. A by-URL server starts disabled and turns on once automatic auth setup succeeds or credentials are added by hand.

What happens on a request

Every request to a remote-backed server passes through the proxy, which does more than forward bytes:

• The caller’s Authorization header is always dropped and replaced with the credential the Control Plane resolved for that caller. A client’s own token is never forwarded upstream.
• Origin, Referer, and Cookie are dropped. Upstream servers with DNS-rebinding protection reject a forwarded browser origin, and forwarding cookies would leak session state upstream.
• Accept-Encoding is dropped so responses arrive decodable and can be inspected.
• Configured upstream headers are applied last and win on conflict. A header configured with an empty value removes that header instead of sending it blank.
• On an upstream 401 or 403, the WWW-Authenticate challenge is replaced with one naming this server’s own resource metadata. Relaying the upstream challenge would point the client at the wrong authorization server.

Private servers additionally run per-tool access checks. Tool lists are filtered to the tools the caller may connect to, and tool calls are checked before they are forwarded. Public servers bypass server-level access control by design, so per-tool checks are skipped for them too.

The proxy does not retry. A failed upstream request is relayed as it came back, including a synthesized JSON-RPC error when an upstream returns a 2xx body that is not valid JSON-RPC.

Recording tool metadata

A remote server proxies tools/list live, so the tool list itself is never stored. Tool metadata is different: the display title and the four MCP annotation hints (readOnlyHint, destructiveHint, idempotentHint, and openWorldHint) are recorded per tool name and held by the Control Plane.

Recording matters because access control reads it. The disposition that per-tool mcp:connect checks evaluate resolves from this stored metadata, not from the upstream response, so no tools/call waits on an upstream tools/list. A server with no recorded metadata resolves to the empty disposition, which leaves enforcement on it unchanged.

The Inspect tab is where this happens. Clicking Connect opens a session against the live server and lists the tools it advertises alongside what is stored for each one. Tools advertised for the first time are recorded automatically. Stored values win over advertised ones when the two disagree, and a stored value left unset falls back to what the server advertises.

Reconciling stored metadata against the live server

When stored metadata and the live session disagree, a panel above the tool list reports how many tools differ and offers Sync annotations. It covers two cases:

• Changed — the tool is still advertised, but at least one stored field no longer matches
• Removed — metadata is stored under a tool name the session no longer advertises

Syncing rewrites stored metadata to match the live session, which also drops the entries for removed tools. The panel header states how many removals a sync will make before it runs.

Tool metadata is keyed by tool name. Renaming a tool upstream separates it from the metadata recorded under its old name, so the rename reads as one removed tool and one new tool rather than as a change.

Reading tool metadata requires the mcp:read scope, and recording or syncing it requires mcp:write. Both paths apply only to remote and tunneled servers. A built server stores its tool definitions when a deployment is processed, annotations included, so there is nothing to record and the request is refused. See How tools appear on a server for how the two backends diverge.

Editing a server afterwards

The server detail page carries everything that can change after creation:

• Overview — tool calls, failed calls, error rate, and average latency, with tool call trends and top tools
• Inspect — the live tool list and the stored tool metadata reconciled against it, described in Recording tool metadata
• Team Access — which members and roles can read, write, or connect
• Settings — display name, upstream URL, upstream headers, visibility, custom slug and domain, publishing, and deletion, plus the Authentication section covering the identity provider callers authenticate against and the remote identity providers used to reach the upstream

Deleting a remote server removes its stored headers, linked server configs, and endpoints. Deleting only the linked MCP server config leaves the remote record in place, and it can be re-linked to a new server config afterwards.