Connect to external tools with MCP

The Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools and data sources. With MCP, your agent can query databases, integrate with APIs like Slack and GitHub, and connect to other services without writing custom tool implementations. MCP servers can run as local processes, connect over HTTP, or execute directly within your SDK application.

This page covers MCP configuration for the Agent SDK. To add MCP servers to the Claude Code CLI so they load in every project, see MCP installation scopes.

Quickstart

This example connects to the Claude Code documentation MCP server using HTTP transport and uses allowedTools with a wildcard to permit all tools from the server.

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Use the docs MCP server to explain what hooks are in Claude Code",
  options: {
    mcpServers: {
      "claude-code-docs": {
        type: "http",
        url: "https://code.claude.com/docs/mcp"
      }
    },
    allowedTools: ["mcp__claude-code-docs__*"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    options = ClaudeAgentOptions(
        mcp_servers={
            "claude-code-docs": {
                "type": "http",
                "url": "https://code.claude.com/docs/mcp",
            }
        },
        allowed_tools=["mcp__claude-code-docs__*"],
    )

    async for message in query(
        prompt="Use the docs MCP server to explain what hooks are in Claude Code",
        options=options,
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

The agent connects to the documentation server, searches for information about hooks, and returns the results.

Add an MCP server

You can configure MCP servers in code when calling query(), or in a .mcp.json file loaded via settingSources.

In code

Pass MCP servers directly in the mcpServers option. This example starts a local filesystem MCP server for /Users/me/projects. Replace that path with a directory on your machine:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "List files in my project",
  options: {
    mcpServers: {
      filesystem: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
      }
    },
    allowedTools: ["mcp__filesystem__*"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    options = ClaudeAgentOptions(
        mcp_servers={
            "filesystem": {
                "command": "npx",
                "args": [
                    "-y",
                    "@modelcontextprotocol/server-filesystem",
                    "/Users/me/projects",
                ],
            }
        },
        allowed_tools=["mcp__filesystem__*"],
    )

    async for message in query(prompt="List files in my project", options=options):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

From a config file

Create a .mcp.json file at your project root. The file is picked up when the project setting source is enabled, which it is for default query() options. If you set settingSources explicitly, include "project" for this file to load. Replace /Users/me/projects with a directory on your machine:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

Connection timing

Claude Code registers the servers you pass in options.mcpServers at startup and emits the init message once the first-turn wait, if any, resolves. Without options.mcpServers, Claude Code waits 2 seconds for pending servers before the first turn, so servers loaded from settings files such as .mcp.json commonly show pending at init. When each options.mcpServers server connects, and whether it delays the first turn, depends on its type:

Server type	Delays the first turn?	First-turn wait timeout
stdio server, or HTTP/SSE server without a cached tool list	Yes, until it connects	`MCP_TIMEOUT`, 30 seconds by default; the connection fails at that deadline
Remote server with a cached tool list, saved by Claude Code from a previous connection	No; the cached tools are available from the first turn	None; connects on its first tool call, and that deferred connect has its own timeout
In-process SDK server	Yes, until it connects and lists its tools	None; the connect and tool listing requests each have their own timeout

To block startup itself at a separate, earlier phase than the first-turn wait, before the init message is sent:

Set MCP_CONNECTION_NONBLOCKING to 0 to block on the whole connection batch. Claude Code caps that wait at 5 seconds by default. Adjust the cap with the MCP_CONNECT_TIMEOUT_MS environment variable, in milliseconds. Servers still pending at that deadline keep connecting in the background.
Set alwaysLoad: true on a server’s config to make its tools available at their full schemas on the first turn, exempt from tool search deferral. Claude Code waits at startup for that server’s tools, capped at the same deadline, while other servers keep connecting in the background; a remote server with a cached tool list supplies them without connecting, per the table above.

The system message with subtype init reports each server’s status at the moment it’s emitted; see Error handling for reading those statuses.

Allow MCP tools

MCP tools require explicit permission before Claude can use them. Without permission, Claude will see that tools are available but won’t be able to call them.

Tool naming convention

MCP tools follow the naming pattern mcp__<server-name>__<tool-name>. For example, a GitHub server named "github" with a list_issues tool becomes mcp__github__list_issues.

Auto-approve with allowedTools

Use allowedTools to auto-approve specific MCP tools so Claude can use them without a permission prompt:

const _ = {
  options: {
    mcpServers: {
      // your servers
    },
    allowedTools: [
      "mcp__github__*", // All tools from the github server
      "mcp__db__query", // Only the query tool from db server
      "mcp__slack__send_message" // Only send_message from slack server
    ]
  }
};

options = ClaudeAgentOptions(
    mcp_servers={
        # your servers
    },
    allowed_tools=[
        "mcp__github__*",  # All tools from the github server
        "mcp__db__query",  # Only the query tool from db server
        "mcp__slack__send_message",  # Only send_message from slack server
    ],
)

Wildcards (*) let you allow all tools from a server without listing each one individually.

Prefer allowedTools over permission modes for MCP access. permissionMode: "acceptEdits" does not auto-approve MCP tools (only file edits and filesystem Bash commands). permissionMode: "bypassPermissions" does auto-approve MCP tools but also disables most other safety prompts, which is broader than necessary; see How permissions are evaluated for the prompts that remain. A wildcard in allowedTools grants exactly the MCP server you want and nothing more. See Permission modes for a full comparison.

Discover available tools

To see what tools an MCP server provides, check the server’s documentation or inspect the tools array in the system init message. MCP tool names start with mcp__. Claude Code emits the init message after the first-turn connection wait for servers passed in options.mcpServers, so the tools array lists the mcp__ tools of each server that has connected by then, plus those of servers with a cached tool list, which connect on first use. Tools of any other server that hasn’t connected are absent; see Error handling for reading each server’s status. This filter prints the MCP tool names:

import { query } from "@anthropic-ai/claude-agent-sdk";

const

Agent SDK

Build agents

Core concepts

Input and output

Extend with tools

Customize behavior

Control and observability

Deployment

SDK references

Connect to external tools with MCP

Quickstart

Add an MCP server

In code

From a config file

Connection timing

Allow MCP tools

Tool naming convention

Auto-approve with allowedTools

Discover available tools

​Quickstart

​Add an MCP server

​In code

​From a config file

​Connection timing

​Allow MCP tools

​Tool naming convention

​Auto-approve with allowedTools

​Discover available tools

Quickstart

Add an MCP server

In code

From a config file

Connection timing

Allow MCP tools

Tool naming convention

Auto-approve with allowedTools

Discover available tools