Skip to main content

​
What is MCP?

The Model Context Protocol (MCP) is an open standard for exposing tools, data, prompts, and other capabilities to AI applications. If you are new to the protocol, start with: mcp-agent treats MCP servers as the “toolbelt” for your agents: they provide the commands and resources that LLMs can invoke. Any MCP client (Claude Desktop, Cursor, VS Code extensions, custom apps) can connect to those same servers—including the ones you expose with mcp-agent.

​
Learn by example

The examples/mcp directory contains runnable demonstrations for the major MCP capabilities:
ExampleWhat it showsTransport
mcp/mcp_streamable_httpConnecting to a remote HTTP MCP server with streaming responsesstreamable_http
mcp/mcp_sseSubscribing to an SSE MCP serversse
mcp/mcp_websocketsBi-directional communication over WebSocketswebsocket
mcp/mcp_elicitationUsing elicitation (interactive prompts)stdio + elicitation
mcp/mcp_prompts_and_resourcesListing and consuming prompts/resourcesstdio
mcp/mcp_rootsBrowsing server roots (filesystem-style access)stdio
Each folder includes both the server configuration and client scripts that connect via gen_client, making them ideal templates when wiring new transports or capabilities into your own project.

​
Configuring MCP servers in mcp-agent

Add MCP servers to mcp_agent.config.yaml. mcp-agent will automatically launch stdio servers, or connect to remote ones via SSE, WebSocket, or streamable HTTP. 
mcp:
  servers:
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/data"]

    database:
      command: "python"
      args: ["database_server.py"]
      env:
        DATABASE_URL: "postgresql://localhost/mydb"

    docs_api:
      transport: "streamable_http"
      url: "https://api.example.com/mcp"
      headers:
        Authorization: "Bearer ${API_TOKEN}"
Configure secrets in mcp_agent.secrets.yaml or environment variables (see Specify Secrets) and mcp-agent will merge them automatically at startup.

​
Using MCP capabilities from an Agent

Once a server is configured, every attached agent and AugmentedLLM can access its tools, resources, prompts, and roots: 
from mcp_agent.agents.agent import Agent

agent = Agent(
    name="mcp_demo",
    instruction="Use all available MCP capabilities.",
    server_names=["filesystem", "database", "docs_api"],
)

async with agent:
    tools = await agent.list_tools()
    resources = await agent.list_resources()
    prompts = await agent.list_prompts()
    roots = await agent.list_roots()

    print("Tools:", [t.name for t in tools.tools])
    print("Resources:", [r.uri for r in resources.resources])
    print("Prompts:", [p.name for p in prompts.prompts])
    print("Roots:", [r.uri for r in roots.roots])
Key primitives you will use:
  • Tools: await agent.call_tool("tool_name", arguments={...})
  • Resources: await agent.list_resources() / await agent.read_resource(uri)
  • Prompts: await agent.list_prompts() / await agent.get_prompt(name, arguments)
  • Roots: await agent.list_roots() for filesystem-style exploration
  • Sampling: Some servers expose sampling endpoints; see examples/mcp/mcp_sampling

​
Connecting programmatically (gen_client)

Use gen_client for a lightweight MCP client in Python. The examples above rely on it; here is the minimal template: 
from mcp_agent.app import MCPApp
from mcp_agent.mcp.gen_client import gen_client

app = MCPApp(name="mcp_client_demo")

async def main():
    async with app.run():
        async with gen_client("filesystem", app.server_registry, context=app.context) as session:
            tools = await session.list_tools()
            print("Tools:", [t.name for t in tools.tools])
Swap "filesystem" for any server defined in your config. For more advanced patterns (persistent connections, aggregators) see Connecting to MCP Servers.

​
Authentication & security

Many MCP servers require authentication—API tokens, OAuth flows, or custom headers. mcp-agent supports:
  • Secrets from mcp_agent.secrets.yaml or environment variables
  • Header-based tokens for remote transports
  • Full OAuth flows (loopback, pre-authorised tokens, Redis-backed token storage)
See Server Authentication for detailed configuration based on the OAuth examples under examples/basic/oauth_basic_agent and examples/oauth.

​
Additional resources