MCP Capabilities

mcp-agent is built on top of the Model Context Protocol (MCP). Agents connect to MCP servers to gain tools, data, prompts, and filesystem-style access. If you are new to the protocol, start with the official MCP introduction; this page shows how MCP fits into mcp-agent.

MCP primitives at a glance

Tools

Functions exposed by MCP servers—use agent.call_tool or let an AugmentedLLM invoke them during generation.

Resources

Structured content retrievable via URIs (agent.list_resources, agent.read_resource).

Prompts

Parameterised templates listed with agent.list_prompts and fetched via agent.get_prompt.

Roots

Named filesystem locations agents can browse; list with agent.list_roots.

Elicitation

Servers can pause a tool to request structured user input; see the elicitation example under examples/mcp.

Sampling

Some servers provide LLM completion endpoints; try the sampling demo in examples/mcp.

Supported Capabilities → covers each primitive in depth.

Example-driven overview

The quickest way to learn is to run the projects in examples/mcp:

Example	Focus	Transport
`mcp_streamable_http`	Connect to a remote HTTP MCP server with streaming responses	`streamable_http`
`mcp_sse`	Subscribe to an SSE MCP server	`sse`
`mcp_websockets`	Bi-directional WebSocket communication	`websocket`
`mcp_prompts_and_resources`	List and consume prompts/resources	stdio
`mcp_roots`	Browse server roots (filesystem access)	stdio
`mcp_elicitation`	Handle elicitation (interactive prompts)	stdio

Each example includes a minimal server configuration and client code that connects via gen_client.

Configuring servers

Add servers to mcp_agent.config.yaml:

mcp:
  servers:
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/data"]

    docs_api:
      transport: "streamable_http"
      url: "https://api.example.com/mcp"
      headers:
        Authorization: "Bearer ${DOCS_API_TOKEN}"

Store secrets in mcp_agent.secrets.yaml, environment variables, or preload settings (see Specify Secrets).

Using MCP capabilities from an agent

from mcp_agent.agents.agent import Agent

agent = Agent(
    name="mcp_demo",
    instruction="Use all available MCP capabilities.",
    server_names=["filesystem", "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])

Common API calls:

await agent.call_tool("tool_name", arguments={...})
await agent.read_resource(uri)
await agent.get_prompt(name, arguments)
await agent.list_roots()

AugmentedLLMs inherit these capabilities automatically.

Lightweight MCP client (`gen_client`)

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

For persistent connections or aggregators, see Connecting to MCP Servers.

Authentication

Static headers/API keys go in headers and pull values from secrets or env variables.
OAuth flows (loopback, interactive tool flow, pre-authorised tokens) are fully supported; see Server Authentication.
Examples under examples/basic/oauth_basic_agent and examples/oauth demonstrate each pattern.

Detailed reference

Transport configurations

STDIO (Standard Input/Output)

Best for local subprocess servers:

mcp:
  servers:
    filesystem:
      transport: "stdio"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem"]

Server-Sent Events (SSE)

Ideal for streaming responses and near-real-time updates:

mcp:
  servers:
    sse_server:
      transport: "sse"
      url: "http://localhost:8000/sse"
      headers:
        Authorization: "Bearer ${SSE_TOKEN}"

WebSocket

Bi-directional, persistent connections:

mcp:
  servers:
    websocket_server:
      transport: "websocket"
      url: "ws://localhost:8001/ws"

Streamable HTTP

HTTP servers with streaming support:

mcp:
  servers:
    http_server:
      transport: "streamable_http"
      url: "https://api.example.com/mcp"
      headers:
        Authorization: "Bearer ${API_TOKEN}"

Build a minimal MCP server

demo_server.py

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Resource Demo MCP Server")

@mcp.resource("demo://docs/readme")
def get_readme():
    """Provide the README file content."""
    return "# Demo Resource Server\n\nThis is a sample README resource."

@mcp.prompt()
def echo(message: str) -> str:
    """Echo the provided message."""
    return f"Prompt: {message}"

if __name__ == "__main__":
    mcp.run()

Agent configuration for that server

mcp_agent.config.yaml

execution_engine: asyncio

mcp:
  servers:
    demo:
      command: "python"
      args: ["demo_server.py"]

openai:
  default_model: "gpt-4o-mini"

Using tools, resources, prompts, and roots

# Tools
result = await agent.call_tool("read_file", {"path": "/data/config.json"})

# Resources
resource = await agent.read_resource("file:///data/report.pdf")

# Prompts
prompt = await agent.get_prompt("code_review", {"language": "python", "file": "main.py"})

# Roots
roots = await agent.list_roots()

Elicitation example

from mcp.server.fastmcp import FastMCP, Context
from mcp.server.elicitation import (
    AcceptedElicitation,
    DeclinedElicitation,
    CancelledElicitation,
)
from pydantic import BaseModel, Field

mcp = FastMCP("Interactive Server")

@mcp.tool()
async def deploy_application(app_name: str, environment: str, ctx: Context) -> str:
    class DeploymentConfirmation(BaseModel):
        confirm: bool = Field(description="Confirm deployment?")
        notify_team: bool = Field(default=False)
        message: str = Field(default="")

    result = await ctx.elicit(
        message=f"Confirm deployment of {app_name} to {environment}?",
        schema=DeploymentConfirmation,
    )

    match result:
        case AcceptedElicitation(data=data):
            return "Deployed" if data.confirm else "Deployment cancelled"
        case DeclinedElicitation():
            return "Deployment declined"
        case CancelledElicitation():
            return "Deployment cancelled"

Capability matrix

Primitive	STDIO	SSE	WebSocket	HTTP	Status
Tools	✅	✅	✅	✅	Fully supported
Resources	✅	✅	✅	✅	Fully supported
Prompts	✅	✅	✅	✅	Fully supported
Roots	✅	✅	✅	✅	Fully supported
Elicitation	✅	✅	✅	✅	Fully supported
Sampling	✅	✅	✅	✅	Supported via examples

Example gallery

Prompts & Resources

Complete example with prompts and resources

MCP Server Examples

All MCP primitive examples

Agent Server

Agents as MCP servers with all primitives

MCP Specification

Official MCP specification

Get Started

MCP Agent SDK

Deployment

Test and Evaluate

Reference

MCP primitives at a glance

Tools

Resources

Prompts

Roots

Elicitation

Sampling

Example-driven overview

Configuring servers

Using MCP capabilities from an agent

Lightweight MCP client (`gen_client`)

Authentication

Detailed reference

Transport configurations

Build a minimal MCP server

Agent configuration for that server

Using tools, resources, prompts, and roots

Elicitation example

Capability matrix

Example gallery

Prompts & Resources

MCP Server Examples

Agent Server

MCP Specification

​MCP primitives at a glance

Tools

Resources

Prompts

Roots

Elicitation

Sampling

​Example-driven overview

​Configuring servers

​Using MCP capabilities from an agent

​Lightweight MCP client (gen_client)

​Authentication

​Related documentation

​Detailed reference

​Transport configurations

​Build a minimal MCP server

​Agent configuration for that server

​Using tools, resources, prompts, and roots

​Elicitation example

​Capability matrix

​Example gallery

Prompts & Resources

MCP Server Examples

Agent Server

MCP Specification

​Related documentation

MCP primitives at a glance

Example-driven overview

Configuring servers

Using MCP capabilities from an agent

Lightweight MCP client (`gen_client`)

Authentication

Related documentation

Detailed reference

Transport configurations

Build a minimal MCP server

Agent configuration for that server

Using tools, resources, prompts, and roots

Elicitation example

Capability matrix

Example gallery

Related documentation