Skip to content

mcp.md

Latest commit

 

History

History
92 lines (69 loc) · 2.93 KB

mcp.md

File metadata and controls

92 lines (69 loc) · 2.93 KB
Raw

MCP (Model Context Protocol) Integration

Overview

MCP allows the agent to connect to external tool servers, extending the bundled tool suite with tools from the MCP server ecosystem.

Configuring MCP Servers

Declare MCP servers in the config file:

# Stdio transport: launch a local subprocess
[mcp.servers.filesystem]
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/project"]

[mcp.servers.github]
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_xxx" }
startup_timeout_ms = 30000

# SSE transport: connect to a remote SSE server
[mcp.servers.database]
transport = "sse"
url = "http://localhost:3001/sse"

# Streamable HTTP transport: HTTP POST communication
[mcp.servers.remote-tools]
transport = "streamable-http"
url = "https://tools.example.com/mcp"
headers = { Authorization = "Bearer xxx" }

Transport Types

Transport Description Use Case
stdio Launch local subprocess, communicate via stdin/stdout Local MCP servers (npx, uvx)
sse GET for SSE event stream, POST for requests Remote MCP servers
streamable-http HTTP POST, supports SSE streaming responses Remote MCP servers

Startup Timeout

Configured MCP servers are connected concurrently during startup. Each server has a startup timeout covering transport connection, initialize, and tools/list. The default is 30000 milliseconds.

[mcp.servers.slow-tools]
transport = "stdio"
command = "npx"
args = ["-y", "slow-mcp-server"]
startup_timeout_ms = 60000

Increase startup_timeout_ms for servers that need extra time for first-run setup, package downloads, remote authentication, or slow network handshakes.

Deferred Loading

MCP tools can be registered as "deferred" — their full schema is not loaded into the system prompt at startup, reducing initial token usage. The LLM discovers deferred tools via the ToolSearch tool when needed.

[mcp.servers.large-toolset]
transport = "stdio"
command = "npx"
args = ["-y", "my-mcp-server"]
deferred = true    # Don't load tool schemas at startup
deferred Behavior
false (default for config servers) Tool schemas included in system prompt at startup
true Tools registered but schemas loaded on-demand via ToolSearch

Use deferred = true for MCP servers with many tools to keep the initial system prompt small.

Tool Naming

  • MCP tool names are used directly when there's no conflict
  • On conflict with built-in or other MCP tools, names are auto-prefixed: mcp__{server}__{tool}

Startup Flow

  1. Connect to all configured MCP servers
  2. Perform MCP protocol handshake (initialize) for each server
  3. Discover available tools (tools/list)
  4. Register tools in the tool registry — the agent uses them like built-in tools
  5. Gracefully close all connections on exit