An MCP server is a service that publishes tools in a standard format any MCP-capable client can call. Instead of hand-writing a tool definition for every internal API, you stand up (or subscribe to) an MCP server and point Claude at it. On the Claude platform there are two documented ways to do that, with very different platform availability — so start by checking which door is open to you.
| Surface | How it works | Availability (July 2026) |
|---|---|---|
| MCP connector (Messages API) | You list servers in the request; the API calls them during the turn | Beta on the Claude API, Claude Platform on AWS, and Microsoft Foundry; not on Bedrock or Vertex AI |
| Managed Agents MCP | Servers declared on a persistent agent; credentials held in vaults | Managed Agents is beta on the Claude API and Claude Platform on AWS only |
On Amazon Bedrock and Google Vertex AI, neither surface is available. The workable pattern there is classic client-side tool use: your application connects to the MCP servers itself, translates their tools into user-defined tool definitions (a name, description, and JSON Schema input_schema), executes calls when Claude returns tool_use blocks, and sends back tool_results. More work, same outcome.
Surface 1: the MCP connector on the Messages API
The connector is enabled with the beta flag mcp-client-2025-11-20. A request supplies an mcp_servers list plus a matching mcp_toolset entry in tools that references the server by name — the toolset entry is what actually grants Claude access to the server's tools, which is your first permission-scoping lever: declaring a server without granting its toolset exposes nothing.
Surface 2: MCP on Managed Agents, with vaults
On Managed Agents, MCP servers are declared on the persistent agent object as {type: "url", name, url} entries using Streamable HTTP transport — deliberately with no auth field. Authentication lives elsewhere, in vaults: workspace-scoped credential containers attached to sessions via vault_ids. Anthropic matches credentials to servers by URL and auto-refreshes OAuth tokens using the stored refresh token.
The security property that makes this pattern enterprise-friendly: vaulted credentials never enter the agent's sandbox. The container sees only an opaque placeholder; the real secret is injected by Anthropic-side proxies as the request leaves the sandbox. Even code running under a successful prompt injection cannot read or exfiltrate the credential. The corollary is a documented anti-pattern to enforce in review: never paste API keys into the system prompt or user messages — they persist in the session's event history.
Practical constraints to plan around: credential types are mcp_oauth and static_bearer for MCP servers (keyed by server URL) plus environment_variable for CLIs and direct API calls; a vault holds at most 20 credentials; secret fields are write-only; and credentials are not validated until session runtime — a bad token surfaces as a session.error event mid-run, not as a creation failure. Also note that MCP server auth requires OAuth bearer tokens, not the service's native REST API keys: a Notion ntn_ integration token will not work as a vault credential for the Notion MCP server.
Permission scoping, layer by layer
Network. Managed Agents cloud environments support a limited network policy — deny-by-default egress with an allowed_hosts list. Under limited networking you must either set allow_mcp_servers: true or list every MCP server domain in allowed_hosts; otherwise MCP tools fail silently, which is a common first-run surprise.
Grant. The mcp_toolset entry controls which declared servers the agent may use; an agent supports up to 20 MCP servers with unique names.
Approval. Tool permission policies apply: always_ask pauses the session until your application sends a confirmation event, which is the right default for write-capable enterprise tools while you build trust.
Server-side. As recommended practice, scope the credential itself at the source system — a read-only service account for a research agent, a queue-scoped token for a triage agent. The platform layers limit exposure; least privilege at the source limits blast radius.
Operational notes
Two documented behaviors worth knowing before launch. First, if an MCP tool returns more than 100K tokens, the output is automatically offloaded to a file in the sandbox and the agent gets a truncated preview plus a file path — design servers to return compact results anyway. Second, before the first production run, reconcile the full chain: every expected action maps to a granted toolset, every server has a vault credential, every server host is reachable under your network policy. A session that discovers a missing dependency mid-run flails.
Where to go next
Scaling past one server? Read multi-server MCP. For the connector's request shape see the MCP connector article, and for credential mechanics see Managed Agents vaults.