Documentation Index
Fetch the complete documentation index at: https://mintlify.com/anthropics/claude-agent-sdk-python/llms.txt
Use this file to discover all available pages before exploring further.
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"
}
}
}
