Signing In to Upstream MCP Servers With OAuth, Once

Separate Provider Login From Agent Access

The useful mental model is two different trust relationships. First, a workspace connects to an upstream MCP server or provider using OAuth. That relationship belongs near the source because it is about the provider, its consent screen, its refresh-token behavior and the scopes it issues. Second, each agent connects to your MCP layer with a credential that expresses what that agent may do. Mixing those layers is what creates repeated sign-ins, overbroad local secrets and confusing revocation paths.

OAuth 2.0 defines scoped access tokens issued by an authorization server to a client after authorization by the resource owner. The MCP authorization specification applies OAuth-style authorization to HTTP-based MCP servers: a protected MCP server acts as a resource server, clients send bearer tokens in the Authorization header, and servers reject missing, invalid or insufficient tokens with ordinary HTTP authorization errors. That is a good fit for remote MCP. It is a poor reason to make every desktop client, CI job and experimental agent perform the same provider login separately.

With a central MCP layer, the upstream sign-in happens once per source connection. Agent clients then point at one MCP endpoint and use their own agent credentials. The upstream provider still sees a legitimate OAuth client, but the local agent config does not contain the provider refresh token. The related guide on scoping API keys for AI agents covers the second half of the design: source allowlists, read/write grants and rotation for the agent-facing credential.

Use OAuth Scopes At The Source

The upstream grant should be narrow before an agent policy ever runs. If the source needs read-only issue search, request the provider scope that supports that behavior; do not ask for repository administration and hope the agent never chooses a write tool. MCP authorization also has a scope-selection model: a server can advertise required scopes with a WWW-Authenticate challenge, and clients should request only the scopes needed for the operation. That gives the upstream connection a principled place to remain small.

The central layer should store enough metadata to make later reviews intelligible: provider, upstream server URL, OAuth client id or registration reference, granted scope string, resource audience, token expiry, refresh status, connector owner and last successful authorization time. It should not log raw access tokens or refresh tokens. When an upstream server responds with 401 Unauthorized, the source needs reauthentication. When it responds with 403 Forbidden and an insufficient-scope challenge, the source needs a deliberate scope upgrade, not a silent retry with a broader grant.

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
  scope="issues:write",
  resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"

Treat that challenge as a change request. A read-only support agent should not cause the workspace to request write scopes just because it attempted an issue mutation. The source connection can support a wider grant for another workflow, but that should be explicit and reviewable.

Keep Client Configs Boring

Once the provider login is centralized, local agent setup becomes deliberately plain. Claude Code can add a remote HTTP MCP server from a URL, and it supports headers for bearer-token authentication. In this pattern the bearer token is the agent-facing credential, not a GitHub, Notion or database secret.

claude mcp add --transport http spyn3 https://api.spyn3.com/agent/mcp --header "Authorization: Bearer $SPYN3_AGENT_KEY"

VS Code supports MCP configuration in workspace and user locations, including a workspace .vscode/mcp.json file with a top-level servers object. Its own documentation warns against hardcoding sensitive information such as API keys in those files. The same shape can point an editor at a central endpoint while keeping the secret in the user's auth mechanism or secret store.

{
  "servers": {
    "spyn3": {
      "type": "http",
      "url": "https://api.spyn3.com/agent/mcp"
    }
  }
}

The operational benefit is not only fewer browser prompts. It is fewer places where a provider credential can leak. A project repository can carry the endpoint configuration, while each developer, service account or automation runner receives a scoped agent credential appropriate for its job. If you later move from one client to another, the migration is the endpoint and the agent credential, not every upstream OAuth connection. That is the same architectural pressure discussed in switching AI agents without rebuilding integrations.

Verify With Protocol Calls

Do not verify this design by staring at the provider dashboard alone. Verify it at the MCP boundary. The tools specification says clients discover tools with tools/list and invoke tools with tools/call; it also allows the available tool set to vary by the authorization presented on the request. That makes the agent credential observable. The same upstream OAuth connection can be present, while two agent keys receive different tools because their source and grant policies differ.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "github.search_issues",
    "arguments": {
      "query": "repo:acme/app label:bug auth",
      "limit": 10
    }
  }
}

A good test matrix has three rows. Use a read-only agent key and confirm the read tool succeeds. Use the same key on a write-capable tool and confirm the call is denied before any upstream request is made. Then use a key without the source in its allowlist and confirm the source is unavailable or withheld even though the workspace still has a valid upstream OAuth grant. That proves the provider login is not acting as a universal permission bypass.

Plan Reauthorization And Revocation

Centralizing OAuth makes reauthorization simpler, but it also concentrates responsibility. Put a clear owner on every upstream source connection. Track when the refresh token last worked, which scopes are currently granted, which agent credentials used the source recently and which workflows would be affected by revocation. If a provider revokes the grant or a user removes consent, the MCP layer should surface the upstream as needing reauthentication rather than pretending the tools disappeared.

Revocation has two independent buttons. Revoking an agent key should immediately stop that agent from listing or calling tools, while leaving the upstream source connected for other approved agents. Revoking the upstream OAuth grant should make the source unavailable for everyone until it is reauthorized, even if their agent keys are still valid. Keeping those buttons separate avoids the common incident response mistake of rotating a local client secret when the actual problem is a compromised provider grant, or reauthorizing a provider when the actual problem is one overbroad agent key.

How SPYN3 handles this

When you connect an OAuth-protected MCP server, SPYN3 registers itself as the client where the server allows it, so the consent screen says SPYN3. You sign in once, in the dashboard. The tokens are stored encrypted and refreshed shortly before they expire. Agents never touch them; they authenticate to SPYN3 with their own key. Some servers don't let applications register themselves. For those, SPYN3 says so, and you have to register a client by hand.

What To Review Before Rollout

Before rolling this pattern out, review four concrete artifacts. First, the upstream OAuth app or client registration: redirect URI, allowed scopes, client type and who can administer it. Second, the source record: provider URL, granted scopes, token status and owner. Third, the agent credential policy: allowed sources, read/write grant, expiry and rotation owner. Fourth, the client configuration: one MCP endpoint, no provider tokens, and no database or API secrets hidden in local JSON.

The final check is behavioral. Start a new client session, list tools, open the intended source if your layer uses on-demand toolsets, run one allowed read call and one intentionally denied write call. Record the request ids and audit events. If a client keeps its first tool list for the session, make sure the server still has a direct call path for opened tools or ask the user to restart the session after a source change. This keeps the OAuth win from becoming a stale-tool-list problem.