mcp-connections

name	mcp-connections
description	Work with MCP servers — connect one, add an entry to the server catalog, debug "the agent cannot see my MCP tools" or a failing OAuth flow, or change how connections are probed, prefixed or filtered. Use when the ask involves an external SaaS tool (GitHub, Linear, Notion, Slack, Stripe, Postgres…) and before writing a capability that would just be an API client for one.

MCP connections

Read docs/mcp.md for the model and docs/howto/add-mcp-server.md for adding a catalog entry. Code: app/agents/mcp.py, app/agents/mcp_oauth.py, app/services/mcp_connection.py, app/services/mcp_catalog.py.

Reach for this before writing a capability

If the ask is "let the agent read our Linear issues", the answer is usually a connection, not code. A capability is right for something the platform must guarantee — a budget guard, a sandbox, retrieval that cites sources. MCP is right for the forty SaaS products a company happens to use.

Adding a catalog entry is one object in app/core/catalog/mcp_servers.json. No code. And nothing needs to be in the catalog for a URL to work — the Custom server entry introspects any reachable server.

Personal vs organization

Two kinds, differing in exactly two places and both are the point:

	Personal	Organization
Reached by	Its owner, through a binding to each person's own account	Any agent whose spec names it
Gate	Owner only	mcp:manage
Credential sealed to	The member	The organization
A spec may name it	No - a spec names the service (account: personal, catalog_key) and the owner's connection is found at run time	Yes, account: organization, connection_id

A spec binds a service one of two ways (McpServerRef in app/agents/spec.py). OrgMcpServerRef is the organization's connection, answering for everybody. PersonalMcpServerRef names a catalog key: build_toolsets_for_agent looks up the sender's own connection by that key on every turn - the message's author, never the thread's - and where there is none (an API key, the widget, a schedule, an unlinked chat sender) reports the gap instead of skipping the server, and _with_personal_service_gaps in the runner tells the model what is missing and where the person connects it. A member's connection is never named by id: a published agent that reached different tools depending on who built it could not be reviewed.

A personal connection is sealed to the member rather than an organization because it has none, and its owner may belong to several: binding it to whichever was active would make the token unreadable the moment they switched.

The four behaviours that surprise people

A dead server is skipped, not raised. Each server gets a 3-second tools/list probe before the turn; failures log a warning and the turn proceeds without those tools. Pydantic AI enters every toolset when a run starts, so raising would let one expired token abort every agent that names the connection. The trade is real: a skipped server means the model answers without the tools. /test and last_status are how you find out.

Tools are prefixed with the connection name. github-work → github_work_*. Two servers exposing the same tool name make Pydantic AI raise on duplicates, which aborts the turn.

Two connections reducing to the same prefix are deduplicated, first one wins, with a warning naming the loser. Deployment-managed servers are ordered first.

An allowlist filters before prefixing, so it compares unprefixed names.

OAuth

Five steps in mcp_oauth.py: discover (RFC 9728 → RFC 8414) → dynamic client registration (RFC 7591) → consent URL (PKCE + state + RFC 8707 resource indicator) → exchange → refresh. Split across two HTTP requests because this is a web app, not a CLI.

Every URL in that flow is SSRF-checked and pinned, not just the one somebody typed — discovery means the remote server picks most of the addresses we call. The flow's only client is mcp_oauth._client(), a PinnedAsyncClient (app/core/pinned_http.py): it checks each request's URL with sanitize.resolve_pinned_url and then dials that address, with the original host in Host and in TLS SNI. Nothing resolves the name twice, so there is no window to rebind (#860). Do not add a request path that builds a plain httpx.AsyncClient — _send takes a PinnedAsyncClient so that mistake does not type-check.

A refused hop crosses httpx out of the transport as a UrlRefusedError, and _send answers it with a fixed OAuthError sentence. Catch the narrow type, never ValueError: only the narrow one is a refusal written here, and every other ValueError reported as "this server pointed us at a blocked address" is a confident lie about whose fault a failure was (#861).

Behind HTTP_PROXY/HTTPS_PROXY the proxy does the connecting, so there the pinned address is what the proxy is asked to reach. Honoured deliberately — a proxy-only deployment would otherwise lose OAuth entirely, and the proxy is its own egress control. Do not "fix" that by naming a transport on the client: an explicit transport turns httpx's environment-proxy mounting off, which is how it was broken once already.

Two things the pin does not cover, and neither is an oversight. The consent URL is checked with validate_mcp_url and then handed to a browser that resolves it itself. The connection's own URL is checked at save and resolved again at run time — a point-in-time check (#840), bearable only because an operator typed it. A URL a model chose belongs in neither; it needs safe_download.

An organization's OAuth connection is still the consenting person's grant at the provider. Revoking their access there breaks the organization's server.

MCP tools are not gated

approval_required_tools iterates spec.capabilities only. MCP tools are discovered at run time, so nothing declared them and nothing approves them. Say so plainly when reviewing a change that adds a connection to a published agent — do not imply a gate exists.

Cost is the same story: what a server does on its own side is outside this platform's budget. Only model tokens are counted.

Routes

GET  /api/v1/me/mcp-connections            personal
GET  /api/v1/mcp-connections               organization  (mcp:manage)
POST /api/v1/mcp-connections/{id}/test     probe, list tools, persist last_status
POST /api/v1/mcp-connections/oauth/start   declared above /{id} — that route parses
                                           its segment as a UUID and would 422

PATCH with auth_token: "" clears a stored credential.

Test

frontend/e2e/mcp-servers.spec.ts covers the UI. For the backend, the interesting assertions are the refusals: a personal connection is not bindable by a spec, a connection from another organization is unreachable, and a prefix collision drops the second server rather than aborting the turn.