Using MCP servers from the Claude API

You do not always need a desktop app to use MCP. The Claude API exposes an MCP connector that lets a model call tools on a remote MCP server as part of a normal request.

The MCP connector #

On the Messages API you declare remote servers and reference them from the tool list. The model can then call their tools during the turn, with Anthropic making the MCP connection server-side. It is a beta feature enabled with the mcp-client-2025-11-20 beta header.

pythonclient.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{"type": "url", "url": "https://mcp.example.com/mcp", "name": "example"}],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example"}],
    messages=[{"role": "user", "content": "Use the example tools to ..."}],
)

Both halves are required #

When to use it #

The connector is ideal when your servers are remote and you want the model to reach them without building a host application. If you need local servers, prompts, or fine-grained control over the connection, run a client with an SDK instead. For current model IDs and connector details, check the official Claude API documentation rather than relying on memory.