Skip to content

MCP Integration

Stirrup supports the Model Context Protocol (MCP) for connecting to external tool servers.

Note

Requires pip install stirrup[mcp] (or: uv add stirrup[mcp])

Quick Start

async def main() -> None:
    """Run an agent with MCP tools."""
    # Create client for OpenRouter
    client = ChatCompletionsClient(
        base_url="https://openrouter.ai/api/v1",
        model="anthropic/claude-sonnet-4.5",
        max_tokens=50_000,
    )

    # Create agent with default tools + MCP tools
    agent = Agent(
        client=client,
        name="mcp_example_agent",
        tools=[*DEFAULT_TOOLS, MCPToolProvider.from_config(".mcp/mcp.json")],
        max_turns=20,
    )

    # Run with session context - handles tool lifecycle, logging, and file saving
    async with agent.session(output_dir=Path("./output/mcp_example")) as session:
        task = """You have access to MCP server tools and a code execution environment.
            Using the same implementation as TheAlgorithms/Python (you can use DeepWiki MCP
            to research), write a Python file quicksort.py that implements quicksort and
            another that tests (and times) it.
            When done, call the finish tool including your findings."""

        _finish_params, _history, _metadata = await session.run(task)

Configuration

Create an mcp.json file (e.g., .mcp/mcp.json) with your server configurations. The path is passed to MCPToolProvider.from_config()—use an absolute path or a path relative to where you run your script.

SSE Server (HTTP)

For remote MCP servers that use Server-Sent Events:

{
  "mcpServers": {
    "deepwiki": {
      "url": "https://mcp.deepwiki.com/sse"
    }
  }
}

Stdio Server (Local Process)

For local MCP servers that run as command-line processes:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropics/mcp-server-filesystem", "/path/to/files"]
    }
  }
}

Tool Naming

MCP tools are prefixed with the server name:

  • Server deepwiki with tool search → deepwiki__search
  • Server filesystem with tool read_file → filesystem__read_file

Environment Variables

Use ${VAR_NAME} syntax for secrets:

{
  "mcpServers": {
    "api_server": {
      "url": "https://api.example.com/sse",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Next Steps