Most serious remote Model Context Protocol (MCP) servers — the ones fronting your CRM, ticketing system, or document store — require authentication, and the MCP ecosystem standardizes on OAuth for it. OAuth is the familiar "sign in and grant access" dance that ends with your application holding an access token: a short-lived credential it presents on every request, usually alongside a longer-lived refresh token used to mint new access tokens without bothering the user again.
Here is the part of the MCP connector design that surprises people: the connector plays no part in that dance. Anthropic's documentation is explicit that API consumers are expected to run the OAuth flow themselves, obtain the access token before making the API call, and pass it in the server definition's authorization_token field. The connector then forwards it to your MCP server on each tool call — nothing more.
What the division of labor actually is
| Responsibility | Who handles it |
|---|---|
| Registering an OAuth client with the MCP server | You |
| Running the authorization flow (user consent, redirect, code exchange) | You |
| Storing access and refresh tokens securely | You |
| Refreshing the token before it expires | You |
| Presenting the token to the MCP server during tool calls | The connector |
The refresh point deserves emphasis because it is where production systems break. The Messages API is stateless: each request carries whatever authorization_token value you put in it, and nothing on Anthropic's side refreshes or re-validates it between your calls. If the token expired ten minutes ago, your MCP tool calls start failing — surfacing as mcp_tool_result blocks with is_error: true, not as a clean HTTP 401 from the Messages API itself. Your token-refresh logic therefore belongs before the API call: check expiry, refresh if needed, then send the request with the fresh token.
authorization_token like any other secret your application injects at request time — fetched from your secrets manager, refreshed by your code, never hard-coded, never logged. The connector is a courier, not a keychain.Where the flow itself is specified
Anthropic does not document its own OAuth recipe for MCP; the connector docs point to the authorization section of the MCP specification (Anthropic currently references the 2025-11-25 spec revision) at modelcontextprotocol.io. That spec defines how an MCP server advertises its authorization server and what grant types to use. For development and testing, the docs suggest a shortcut: the MCP inspector tool (npx @modelcontextprotocol/inspector) can walk the flow interactively and hand you a working test token — useful for proving the integration before you build the real token lifecycle.
Designing the token lifecycle for production
A workable production pattern looks like this: run the interactive authorization once per user or per service connection, persist the refresh token in your secrets store, and put a thin token-provider function in front of every Messages call that returns a valid access token (refreshing when the cached one is near expiry). Keep the token's scope as narrow as the server allows — toolset filtering narrows what Claude may call, but only the token's scope narrows what a leaked credential could do. General practices for storing and rotating credentials are covered in secrets management.
Two retention notes for your security review. First, the MCP connector is not eligible for Zero Data Retention — data exchanged with MCP servers follows Anthropic's standard retention policy. Second, this whole do-it-yourself model is specific to the Messages-API connector: Anthropic's separate Managed Agents product (beta, first-party API and Claude Platform on AWS only) takes the opposite approach, storing MCP credentials in server-side vaults and refreshing OAuth tokens for you. If token plumbing is the pain point, that contrast is covered in Managed Agents vaults and Agent SDK vs. Managed Agents.
Where to go next
Check where the connector is available before designing around it, then see defer_loading for keeping large authenticated toolsets affordable.