MCP Types

MCP server configuration and status types for Claude Agent SDK

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]]

type · Literal['stdio']

Server type. Optional for backwards compatibility (defaults to "stdio").

command · str · required

Command to execute (e.g., "node", "python", "npx").

args · list[str]

Command arguments.

env · dict[str, str]

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]]

type · Literal['sse'] · required

Server type.

url · str · required

SSE endpoint URL.

headers · 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]]

type · Literal['http'] · required

Server type.

url · str · required

HTTP endpoint URL.

headers · 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

type · Literal['sdk'] · required

Server type.

name · str · required

Server name identifier.

instance · McpServer · required

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]]

name · str · required

Server name as configured.

status · McpServerConnectionStatus · required

Current connection status.

serverInfo · McpServerInfo

Server information from MCP handshake (available when connected).

{
    "name": str,
    "version": str
}

error · str

Error message (available when status is "failed").

config · McpServerStatusConfig

Server configuration (includes URL for HTTP/SSE servers).

scope · str

Configuration scope (e.g., "project", "user", "local", "claudeai", "managed").

tools · list[McpToolInfo]

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")

Reconnects a disconnected or failed MCP server.

Toggle Server

# Disable server
await client.mcp_toggle("server-name", enabled=False)

# Enable server
await client.mcp_toggle("server-name", enabled=True)

Enables or disables an MCP server.

Send MCP Message

await client.send_mcp_message("server-name", message_data)

Sends a raw MCP message to a server.

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")
)

mcp-config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/data"]
    },
    "remote": {
      "type": "sse",
      "url": "https://api.example.com/mcp"
    }
  }
}

Related Types

• ClaudeAgentOptions - Main configuration including MCP servers
• Errors - Error types for MCP connection failures