Reach a Remote MCP Server in a Single API Request: Implementing the Messages API MCP Connector

Reading the response

With the MCP connector, two unfamiliar content block types come back. Tool execution completes on Anthropic's side, so you don't send results back—you just read and use them.

def walk(response):
    for block in response.content:
        if block.type == "text":
            print("TEXT:", block.text)
        elif block.type == "mcp_tool_use":
            # A tool Claude called; server_name tells you which server
            print(f"CALL: {block.server_name}.{block.name}({block.input})")
        elif block.type == "mcp_tool_result":
            # The execution result; check is_error for failures
            status = "ERROR" if block.is_error else "OK"
            texts = [c.text for c in block.content if c.type == "text"]
            print(f"RESULT[{status}] {block.tool_use_id}: {' '.join(texts)}")
 
walk(response)

Always inspect is_error on mcp_tool_result. Even if a remote tool fails, the API request itself returns 200. In unattended operation, the scariest state is "the request succeeded but the tool failed," so wire is_error straight into your logs and alerts from day one—it makes root-causing far easier later.

Allowlist / denylist design for unattended jobs

This is the part I most want to get across. If you leave every tool open through the connector, Claude can—depending on context—call write or delete tools too. An interactive chat lets you insert a confirmation step; a scheduled job has no such room.

The new toolset lets you decide tool exposure precisely by combining default_config and configs. For unattended jobs I use an allowlist: close everything by default, then open only the read-only tools.

read_only_toolset = {
    "type": "mcp_toolset",
    "mcp_server_name": "calendar",
    "default_config": {"enabled": False},   # disable all tools first
    "configs": {
        "search_events": {"enabled": True}, # open only the reads you need
        "list_events": {"enabled": True},
    },
}

Conversely, when you want "almost everything, minus the dangerous ones," use a denylist. It suits read-centric assistants, or cases where you want a human confirmation before any state change.

guarded_toolset = {
    "type": "mcp_toolset",
    "mcp_server_name": "calendar",
    # default_config omitted (= all tools enabled by default)
    "configs": {
        "delete_all_events": {"enabled": False},       # close destructive ops
        "share_calendar_publicly": {"enabled": False},
    },
}

My operating principle is plain: unattended jobs default to allowlist; only interactive tooling needs a denylist. The reasoning is the asymmetry of a forgotten entry—under an allowlist a slip means "a tool is missing" (harmless), while under a denylist it means "a dangerous tool was left open." How tightly you scope tool permissions for unattended runs pairs well with the "hold authorization in one place" idea I covered in enforcing MCP policy for unattended agents.

The merge order is worth remembering so you don't second-guess yourself: highest to lowest, "per-tool settings in configs → default_config → system defaults." You can lay down defer_loading: true in default_config while overriding just one tool to defer_loading: false in configs.

Multiple servers, and defer_loading as tools grow

You can connect to several MCP servers in one request. List each in mcp_servers and place a matching mcp_toolset in tools. A validation rule to note: each defined server must be referenced by exactly one toolset, or you get an error (a safe-by-default rule that won't let you leave an unused server lying around).

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Cross-check events and tasks; tell me which time blocks look overloaded today."}],
    mcp_servers=[
        {"type": "url", "url": "https://mcp.example1.com/sse", "name": "calendar",
         "authorization_token": "TOKEN1"},
        {"type": "url", "url": "https://mcp.example2.com/sse", "name": "tasks",
         "authorization_token": "TOKEN2"},
    ],
    tools=[
        {"type": "mcp_toolset", "mcp_server_name": "calendar"},
        {
            "type": "mcp_toolset",
            "mcp_server_name": "tasks",
            "default_config": {"defer_loading": True},  # don't send descriptions up front
        },
    ],
    betas=["mcp-client-2025-11-20"],
)

Once tools number in the dozens across servers, their descriptions alone eat context and selection accuracy drops. Laying down defer_loading: true keeps tool descriptions from being sent to the model initially, and combined with the Tool search tool, only the relevant tools surface per query. In my experience, the moment tool counts cross into double digits is the cue to turn on defer_loading.

Cost and caching

Tool calls through the MCP connector are priced the same as ordinary Messages API tool use. You can also include mcp_servers in Batches API requests, and MCP tool calls via batches are priced identically. I push "not urgent but high volume" work—like news gathering—into batches, and it was reassuring that mixing in a remote MCP doesn't change the billing model.

You can attach cache_control to a toolset to place a prompt-caching breakpoint. Tool definitions are a stable, slow-changing part, so they belong on the "unchanging side" of a split-TTL caching design. That's exactly the approach I laid out in splitting prompt caching into 5m and 1h tiers—MCP tool definitions are precisely the block you want on the 1h side.

What to verify before going live

Before integrating, here's the checklist I run every time.

First, no ZDR (Zero Data Retention). The MCP connector is excluded from zero data retention; tool definitions and execution results are kept under the standard retention policy. If you have a ZDR-based requirement, you can't use this feature.

Second, platform differences. The MCP connector works on the Claude API, the Claude Platform on AWS, and Microsoft Foundry, but is not currently available on Amazon Bedrock or Vertex AI. It matters when choosing where you deploy, so confirm it early to avoid rework.

For servers requiring OAuth, the access token passed to authorization_token is obtained and refreshed by you, the caller. Token lifetime is your responsibility, so for scheduled jobs I build a refresh that anticipates expiry into the front of the job. If you just need a token for testing, the OAuth flow in npx @modelcontextprotocol/inspector issues one quickly.

Next step

If you have a URL-reachable remote MCP server on hand, send just one request in the minimal all-tools form and watch with your own eyes how mcp_tool_use and mcp_tool_result actually line up. Once the shape of the response clicks, tightening it down with an allowlist goes surprisingly smoothly from there. For me, once I felt this "the scaffolding is gone" relief once, I started peeling unnecessary resident processes out of my headless jobs one by one.