Using Remote MCP Servers Directly from the Claude API

If an MCP server is reachable over HTTP, the Claude API can connect to it for you. You list the server in the request and the API handles tool discovery and tool calls, so there's no MCP client or agent loop in your code.

The request

The MCP connector is a beta feature. It needs two parts: the server in mcp_servers and a matching mcp_toolset entry in tools.

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const response = await client.beta.messages.create({
  model: 'claude-opus-5-5',
  max_tokens: 16000,
  betas: ['mcp-client-2025-11-20'],
  mcp_servers: [
    {
      type: 'url',
      url: 'https://mcp.example.com/mcp',
      name: 'status-page',
      authorization_token: process.env.STATUS_MCP_TOKEN,
    },
  ],
  tools: [{ type: 'mcp_toolset', mcp_server_name: 'status-page' }],
  messages: [{ role: 'user', content: 'Is the API service healthy right now?' }],
});

for (const block of response.content) {
  if (block.type === 'text') console.log(block.text);
}

When to use it

• Your tools already exist as a remote MCP server (yours or a vendor's).
• You want the simplest possible integration and don't need to inspect each tool call before it runs.

When to run your own client instead

• The server is local (stdio) or on a private network the API can't reach.
• You need approvals, custom logging or argument checks before each call.
• You want to mix MCP tools with your own in-process tools in one loop.

Security notes

• Use a token scoped to the minimum the task needs; the request carries it to the server.
• Only connect servers you trust; their tool descriptions and results go straight into the model's context.
• Check the provider's documentation for which platforms support the connector.