D2 · Tool Design & MCP › Cluster 7 · Building & Consuming MCP Servers

7.3 · Remote MCP Servers & OAuth

Auth for hosted servers

CONCEPT Remote servers are third-party HTTPS endpoints you connect over the wire

A remote MCP server is one publicly exposed over HTTP (Streamable HTTP or SSE) at an https:// URL, versus a local stdio server the host launches as a child process. Companies deploy remote MCP servers so developers can connect to their services — the connector docs list examples such as Notion, Asana, Stripe, Sentry, GitHub, and others. These are third-party services, not owned or endorsed by Anthropic: connect only to servers you trust and review their security terms first — a remote server you attach can read whatever the model shares and is a prompt-injection surface.

🔑 The Messages API connector (7.2), Claude Code (7.4), and Claude Desktop all consume remote servers by URL. The difference is who holds the credential: the connector takes a pre-obtained token in the request; Claude Code runs the OAuth flow interactively for you.

CONCEPT Most remote servers require OAuth; pass a Bearer access token

Many hosted MCP servers require authentication and use OAuth 2.0. For the Messages API connector, you supply the OAuth Bearer access token in the server definition's authorization_token field. Critically, you handle the OAuth flow and token refresh yourself — the API expects a valid access token at request time and does not run the browser flow for you. (Claude Code and Claude Desktop do run the flow — see 7.4.)

To obtain a token for testing, the MCP Inspector (7.5) has a "Quick OAuth Flow": pick the transport, enter the server URL, authorize in the browser, then copy the access_token into authorization_token.
⚠️ MCP OAuth tokens are not the same as a service's native REST API key. A hosted MCP server (e.g. Notion, Slack) typically wants an OAuth Bearer token, not the provider's integration/API key — they're different auth systems and the API key will fail against the MCP endpoint. Access tokens also expire; refresh them before they lapse.

DIAGRAM Where the credential comes from

flowchart TD S["Remote MCP server
needs OAuth"] --> Q{"Which consumer?"} Q -->|"Messages API connector"| A["You obtain the token
(handle OAuth + refresh yourself)"] A --> A2["🟠 Pass authorization_token
in mcp_servers[]"] Q -->|"Claude Code / Desktop"| B["Host runs the OAuth flow"] B --> B2["🟢 /mcp or claude mcp login
token stored + auto-refreshed"] Q -->|"No auth needed"| C["🔵 Omit authorization_token"] classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef net fill:#cce5ff,stroke:#4a90d9,color:#0b3d66; class A2 gate; class B2 ok; class C net;

CODE Attaching an OAuth token to a connector request

Obtain the access token out of band (your OAuth flow, or the Inspector for testing), then place it in authorization_token. Refresh and re-send before it expires.

# Bearer token in the server definition (Messages API connector)
mcp_servers=[
    {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "authenticated-server",
        "authorization_token": "YOUR_ACCESS_TOKEN_HERE",  # OAuth Bearer; you refresh it
    }
]
# Get a token for TESTING via the MCP Inspector:
npx @modelcontextprotocol/inspector
# → set Transport (SSE / Streamable HTTP) → enter URL
# → "Open Auth Settings" → "Quick OAuth Flow" → authorize
# → copy the access_token → paste into authorization_token

TRADE-OFFS API-supplied token vs. host-managed OAuth

Messages API connectorClaude Code / Desktop
Who runs the OAuth flowYou (out of band)The host (browser flow)
Token refreshYour responsibilityAutomatic
Where token livesauthorization_token in each requestStored securely by the host
Best forServer-to-server / programmatic useInteractive developer use
If a server needs no auth, simply omit authorization_token. Never hard-code a long-lived secret where a short-lived OAuth token is expected — and never send a service's REST API key in place of its MCP OAuth token.

EXAM TRAPS

Trap: "The connector runs OAuth for me." → For the Messages API connector, you obtain and refresh the access token yourself and pass it in authorization_token. Only the Claude Code / Desktop hosts run the interactive flow.
Trap: Using a provider's API key as the MCP credential. → Hosted MCP servers usually want an OAuth Bearer token. The service's native API/integration key authenticates a different system and won't work against the MCP endpoint.
Trap: Trusting any remote server. → Remote servers are third-party services, not Anthropic-operated. Connect only to servers you trust; a malicious or compromised server is a prompt-injection and data-exfiltration vector (Cluster 8).
Trap: Assuming a token lasts forever. → OAuth access tokens expire. A connector request with a stale token fails; refresh proactively.

PRACTICE

Q1 · How does an OAuth-protected server get its credential in a Messages API connector request?

You obtain a valid OAuth Bearer access token yourself and put it in the server definition's authorization_token field. The API does not run the OAuth flow — you're also responsible for refreshing the token before it expires.

Q2 · A Notion integration token isn't authenticating the Notion MCP server. Why?

MCP servers use OAuth, a different auth system than the provider's native REST API key. The integration token authenticates Notion's REST API, not its MCP endpoint — you need an OAuth Bearer token for the MCP server.

Q3 · What's the security posture toward remote MCP servers, and why?

Treat them as untrusted third parties — connect only to servers you trust after reviewing their security practices. A remote server sees what the model shares with it and can inject content into the model's context, making it a prompt-injection surface (see 8.1).