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.
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.)
access_token into
authorization_token.DIAGRAM Where the credential comes from
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 connector | Claude Code / Desktop | |
|---|---|---|
| Who runs the OAuth flow | You (out of band) | The host (browser flow) |
| Token refresh | Your responsibility | Automatic |
| Where token lives | authorization_token in each request | Stored securely by the host |
| Best for | Server-to-server / programmatic use | Interactive developer use |
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
authorization_token. Only the
Claude Code / Desktop hosts run the interactive flow.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).