Connecting an MCP Server

Knowledge

Your agent now has a system prompt and a tool definition. But so far, the tool is just a description -- it doesn't actually do anything. In this step, you connect your agent to a real MCP server so it gains real capabilities.

Why MCP Instead of Custom Tool Implementations?

You could implement every tool yourself -- write a function that reads files, one that calls APIs, one that queries databases. But that doesn't scale. MCP (Model Context Protocol) solves this problem:

• Reusability: An MCP server can be used by any agent, regardless of framework
• Standardization: A uniform interface for all tools
• Ecosystem: Hundreds of ready-made MCP servers for common services (GitHub, Slack, databases, file systems)
• Decoupling: The agent doesn't need to know how a tool works internally

Registering an MCP Server as a Tool

The integration happens in three steps:

Step 1 -- Select or start an MCP server

# Example: Start a local filesystem MCP server
npx @modelcontextprotocol/server-filesystem /path/to/project

Step 2 -- Configure the client connection

# Python with MCP Client
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Server configuration
server_params = StdioServerParameters(
    command="npx",
    args=[
        "@modelcontextprotocol/server-filesystem",
        "/path/to/project"
    ]
)

# Establish connection
async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # Initialize session
        await session.initialize()

        # Query available tools
        tools = await session.list_tools()
        print(f"Available tools: {[t.name for t in tools.tools]}")

Step 3 -- Make tools available to the agent

# Convert MCP tools to Anthropic format
def mcp_to_anthropic_tools(mcp_tools):
    return [
        {
            "name": tool.name,
            "description": tool.description,
            "input_schema": tool.inputSchema
        }
        for tool in mcp_tools.tools
    ]

# Give the agent the MCP tools
anthropic_tools = mcp_to_anthropic_tools(tools)

Understand

The Configuration File

In practice, you configure MCP servers via a JSON file. This is the same approach used by Claude Code, Cursor, and other tools:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "/path/to/project"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

Testing the Connection

Before you send the agent off, always test the connection:

# Quick test: Can the agent reach the server?
async def test_mcp_connection(session):
    try:
        tools = await session.list_tools()
        print(f"Connection OK. {len(tools.tools)} tools available:")
        for tool in tools.tools:
            print(f"  - {tool.name}: {tool.description[:60]}...")
        return True
    except Exception as e:
        print(f"Connection failed: {e}")
        return False

Common sources of errors:

• The MCP server isn't started or isn't installed
• Missing environment variables (e.g., API tokens)
• Wrong path in the configuration
• Firewall blocking communication

Apply

Reflect