MCP bearer/OAuth credentials should be scoped by endpoint, not one global mcp token

[serge-ivo]

Critical reassessment against HEAD

This ticket is valid, but the original wording was too broad and partly wrong.

HEAD already made an intentional design choice in #266: an MCP "connection" is not a durable status/nickname record. The connection list is derived from grants on a normalized endpoint, and test results are deliberately not cached because health is a fact about now. That part is defensible and should not be undone by adding a second renameable connection table.

The real remaining problem is narrower: credential material is still provider-wide. The outbound MCP connector is declared as auth: "token", and connectorClient("mcp").token() reads user_api_keys at primary key (user_id, provider), where provider is just mcp. That means one user has one MCP bearer slot for every authenticated MCP endpoint.

That is not enough once the product supports arbitrary authenticated MCP servers.

Problem

A user may connect multiple MCP endpoints with different auth modes, scopes, lifetimes, and credential issuers. A single global mcp token cannot safely answer:

• Which endpoint/resource URL does this credential belong to?
• Which auth mode produced it: bearer fallback, OAuth/DCR/PKCE, setup-token, etc.?
• Which scopes/capabilities were granted?
• When does it expire, and can it refresh unattended?
• Which instance grants are allowed to use it?
• How do reconnect/replace/disconnect avoid breaking another MCP endpoint?

Expected model

Keep the #266 endpoint/grants model for connection identity and health. Add endpoint-scoped credential storage/resolution for MCP auth material.

At minimum, an MCP credential record should be scoped by:

• user/account owner
• normalized MCP endpoint or protected-resource origin, using the same normalization discipline as normalizeMcpEndpoint
• auth mode/type and issuer metadata when known
• encrypted credential material reference, using the existing envelope/vault path or a compatible table
• scopes/capabilities when known
• expiry and refresh metadata when applicable

Bearer-token fallback and OAuth/DCR credentials should resolve through the same endpoint-aware API so the connector does not care how the credential was obtained.

Acceptance criteria

• Credentials for two different MCP endpoints cannot overwrite or authorize each other.
• mcp_list_tools, probeMcpEndpoint, and mcp_call_tool resolve credentials by normalized endpoint/resource, not only provider mcp.
• Consent still remains per (instance, endpoint, tool); credential storage does not replace Outbound MCP consent should be per server and per remote tool, not one global write grant #262 grants.
• No-auth endpoints create no fake secret and still work through the existing grant/test model.
• Credential material is encrypted at rest and redacted from logs, errors, audit rows, traces, and chat/tool transcripts.
• Replacing/disconnecting a credential for one endpoint does not affect other MCP endpoints.
• Expired/revoked credentials fail closed and return a reconnectable state to the UI.
• Backward compatibility is explicit: either migrate existing provider-level mcp credentials or treat them as a legacy fallback with clear UI wording.
• The implementation does not add cached "connected" health state or a second endpoint nickname/id that can drift from enforcement.

Related

• MCP connection setup UI should validate, connect, discover, and test a user-provided endpoint #266: shipped MCP connection/test/grant UI; do not duplicate its storage model
• Outbound MCP connector needs OAuth/browser sign-in for authenticated MCP servers #258: authenticated MCP browser sign-in
• [connectors] dcr-oauth2 — discovery + dynamic client registration + PKCE for user-named endpoints #180: DCR + PKCE for user-named endpoints
• Outbound MCP consent should be per server and per remote tool, not one global write grant #262: per-server/per-tool consent (closed)

[serge-ivo]

Reframed after checking HEAD. The issue should not ask for stored connection/status records; #266 deliberately avoided those. The remaining valid work is endpoint-scoped credential material and endpoint-aware token resolution, because user_api_keys(user_id, provider="mcp") is still global per user.

[serge-ivo]

Fixed in 303dc68 — deployed, migration 0083 applied to prod D1 (run 31097037458: migrations ✓, deploy ✓, smoke ✓).

What changed

Credential material for the outbound MCP connector now lives in mcp_credentials (migration 0083), keyed (user_id, normalized endpoint) — the same key instance_mcp_consent uses, via the same normalizeMcpEndpoint. So reach and credential cannot disagree, …/mcp?v=2 cannot fragment the lookup any more than it can dodge consent, and an endpoint whose query string is its token never puts that token in a key column. Envelope encryption is the platform's existing scheme, untouched: per-row AES-256-GCM DEK wrapped with AES-KW under KEY_ENCRYPTION_KEY.

mcpCall resolves through resolveMcpCredential(env, userId, normalizedEndpoint). mcp_list_tools, mcp_call_tool and probeMcpEndpoint all inherit it, because the probe deliberately goes through the ordinary connector path rather than a test-only shortcut.

No fallback to the provider-wide slot. That was the one tempting mistake here: keeping user_api_keys@provider=mcp as a fallback would look like compatibility and restore the vulnerability in full. An unbound token is one whose server we do not know, and sending it anyway is the disclosure. connectorClient("mcp").token() is no longer on the MCP credential path at all; a test asserts it is never called.

#266 is not undone

Nothing added here has an id, a nickname, or a stored status. A connection is still derived from grants on an endpoint, and health is still a live test. This ticket's own reassessment was right and was followed.

Migration / backfill story

The legacy row records no endpoint, so in general nothing in the DB says which server it belongs to. There is exactly one case where the answer is a fact rather than a guess: the user's instance_mcp_consent rows name exactly one distinct endpoint. The migration adopts it there and nowhere else — picking one of several would be inventing the very binding whose absence is the vulnerability.

Everyone else fails closed, with a refusal that says the token still exists and where to bind it, plus a one-click adopt that copies the ciphertext verbatim under the same KEK (no plaintext is produced to move it), so the change cannot read as data loss.

Also

• credential_expired is its own failure class and connection status. Expiry is a fact when we stored it and sent nothing — unlike a 401, which says nothing about why — and the remedy differs from "no token at all". connectionStatusFor stays a total function, so a new failure class is still a typecheck error rather than a silent fall-through.
• No reveal route. Unlike a user's own AI provider key, an MCP server token has no client-side use, so read-back would be attack surface for nothing. GET returns metadata only; PUT echoes the endpoint and not a token prefix or length (a confirmation string is a credential fragment in a response body, a log, and a browser history entry).
• auth:"none" still reads no credential at all — open servers were not made to require one on the way to fixing the private ones.

Surface

Routes	GET/PUT/DELETE /v1/instances/:id/mcp/credentials (documented in store/openapi.yaml; docs-drift gate green)
Storage	workers/api/src/lib/mcp-credentials.ts
Console	McpConnections.tsx — per-server token state, add/replace/remove, legacy bind-or-discard banner
Docs	platform-docs/connectors.md
Tests	20 new in mcp-credentials.test.ts + 6 in mcp.test.ts — the load-bearing one being "never sends one server's credential to another server"

Full suite green (3853 tests). CI on the commit itself shows one red suite — the pre-existing packages/browser-runner/src/mcp-runtime.test.ts teardown-hook timeout, which also failed on the commit before mine; zero tests failed. It was fixed separately in fix(test): end the sockets…, and CI is green on the following commit.