Overview
The Claude Agent SDK supports Model Context Protocol (MCP) servers for extending Claude’s capabilities with custom tools and resources.
from claude_agent_sdk import ClaudeAgentOptions
mcp_servers = {
"filesystem": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/data"]
}
}
options = ClaudeAgentOptions(mcp_servers=mcp_servers)
McpServerConfig
Union type for all MCP server configuration types.
McpServerConfig = (
McpStdioServerConfig
| McpSSEServerConfig
| McpHttpServerConfig
| McpSdkServerConfig
)
McpStdioServerConfig
Configuration for stdio-based MCP servers (most common).
class McpStdioServerConfig(TypedDict):
type: NotRequired[Literal["stdio"]] # Optional, defaults to stdio
command: str
args: NotRequired[list[str]]
env: NotRequired[dict[str, str]]
Server type. Optional for backwards compatibility (defaults to "stdio").
Command to execute (e.g., "node", "python", "npx").
Environment variables for the server process.
Example
mcp_servers = {
"filesystem": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"],
"env": {"DEBUG": "true"}
},
"custom": {
"command": "python",
"args": ["-m", "my_mcp_server"]
}
}
McpSSEServerConfig
Configuration for Server-Sent Events (SSE) MCP servers.
class McpSSEServerConfig(TypedDict):
type: Literal["sse"]
url: str
headers: NotRequired[dict[str, str]]
HTTP headers for the connection.
Example
mcp_servers = {
"remote-sse": {
"type": "sse",
"url": "https://api.example.com/mcp",
"headers": {
"Authorization": "Bearer token123"
}
}
}
McpHttpServerConfig
Configuration for HTTP-based MCP servers.
class McpHttpServerConfig(TypedDict):
type: Literal["http"]
url: str
headers: NotRequired[dict[str, str]]
HTTP headers for requests.
Example
mcp_servers = {
"api-server": {
"type": "http",
"url": "https://mcp.example.com",
"headers": {
"X-API-Key": "secret"
}
}
}
McpSdkServerConfig
Configuration for in-process MCP servers using the Python MCP SDK.
class McpSdkServerConfig(TypedDict):
type: Literal["sdk"]
name: str
instance: McpServer
MCP server instance from the mcp package.
Example
from mcp.server import Server as McpServer
from claude_agent_sdk import ClaudeAgentOptions
# Create MCP server instance
server = McpServer("my-server")
# Register tools, resources, etc.
@server.list_tools()
async def list_tools():
return [{"name": "my_tool", "description": "Does something"}]
mcp_servers = {
"custom-server": {
"type": "sdk",
"name": "my-server",
"instance": server
}
}
options = ClaudeAgentOptions(mcp_servers=mcp_servers)
MCP Status Types
Types returned by ClaudeSDKClient.get_mcp_status() for querying server connection status.
McpServerConnectionStatus
McpServerConnectionStatus = Literal[
"connected",
"failed",
"needs-auth",
"pending",
"disabled"
]
"connected" - Server is connected and ready"failed" - Connection failed (see error field)"needs-auth" - Server requires authentication"pending" - Connection in progress"disabled" - Server is disabled
McpServerStatus
Status information for a single MCP server.
class McpServerStatus(TypedDict):
name: str
status: McpServerConnectionStatus
serverInfo: NotRequired[McpServerInfo]
error: NotRequired[str]
config: NotRequired[McpServerStatusConfig]
scope: NotRequired[str]
tools: NotRequired[list[McpToolInfo]]
Server name as configured.
status
McpServerConnectionStatus
required
Current connection status.
Server information from MCP handshake (available when connected).{
"name": str,
"version": str
}
Error message (available when status is "failed").
Server configuration (includes URL for HTTP/SSE servers).
Configuration scope (e.g., "project", "user", "local", "claudeai", "managed").
Tools provided by this server (available when connected).{
"name": str,
"description": str,
"annotations": {
"readOnly": bool,
"destructive": bool,
"openWorld": bool
}
}
McpStatusResponse
Response from ClaudeSDKClient.get_mcp_status().
class McpStatusResponse(TypedDict):
mcpServers: list[McpServerStatus]
Example
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
mcp_servers = {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
}
}
client = ClaudeSDKClient(ClaudeAgentOptions(mcp_servers=mcp_servers))
# Check MCP server status
status = await client.get_mcp_status()
for server in status["mcpServers"]:
print(f"Server: {server['name']}")
print(f"Status: {server['status']}")
if server["status"] == "connected":
print(f"Tools: {len(server.get('tools', []))}")
for tool in server.get("tools", []):
print(f" - {tool['name']}: {tool.get('description', 'N/A')}")
elif server["status"] == "failed":
print(f"Error: {server.get('error', 'Unknown')}")
MCP Control Methods
The SDK provides methods for controlling MCP servers:
Reconnect Server
await client.mcp_reconnect("server-name")
Toggle Server
# Disable server
await client.mcp_toggle("server-name", enabled=False)
# Enable server
await client.mcp_toggle("server-name", enabled=True)
Send MCP Message
await client.send_mcp_message("server-name", message_data)
Loading MCP Servers from File
You can load MCP server configurations from a JSON file:
from pathlib import Path
options = ClaudeAgentOptions(
mcp_servers=Path("/path/to/mcp-config.json")
)
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/data"]
},
"remote": {
"type": "sse",
"url": "https://api.example.com/mcp"
}
}
}
