# How Agno Agents Interact with MCP Protocol Services: Complete Integration Guide

> Integrate Agno agents with MCP protocol services using MCPTools and MultiMCPTools. Discover toolkits, manage connections, and enable dynamic authentication for seamless interaction.

- Repository: [Agno/agno](https://github.com/agno-agi/agno)
- Tags: how-to-guide
- Published: 2026-02-23

---

**Yes, Agno agents can natively interact with MCP protocol services using the `MCPTools` and `MultiMCPTools` toolkits, which automatically handle connection lifecycle, tool discovery, and result conversion while supporting dynamic authentication and human-in-the-loop controls.**

The Agno framework (available at `agno-agi/agno`) enables agents and teams to call tools exposed by Model-Context-Protocol (MCP) servers through dedicated toolkit implementations. These toolkits extend Agno's base `Toolkit` class to bridge the gap between Agno's agent runtime and external MCP-compliant services.

## Architecture of MCP Integration in Agno

The integration centers on two primary classes: **`MCPTools`** for single-server connections and **`MultiMCPTools`** for orchestrating multiple endpoints. Both implement the standard Agno `Toolkit` interface, allowing seamless inclusion in any agent's tool configuration.

### Transport and Connection Management

In [`libs/agno/agno/tools/mcp/mcp.py`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/tools/mcp/mcp.py), the `MCPTools.__init__` method (lines 28-74) validates transport configurations including `stdio`, `sse`, and `streamable-http`. When instantiated with a URL, command, or explicit `server_params`, the toolkit stores connection arguments and optional filters like `include_tools` and `exclude_tools`.

The actual connection occurs in `MCPTools._connect` (lines 133-176), which establishes a **`ClientSession`** with the MCP server. For HTTP-based transports, the optional `header_provider` parameter enables dynamic header injection based on runtime context.

### Per-Run Session Handling and Authentication

For scenarios requiring per-request authentication, `MCPTools.get_session_for_run` (lines 75-101) creates dedicated `ClientSession` instances when a `RunContext` is supplied. This method:

- Merges dynamic headers from the `header_provider` callback
- Caches sessions with a default TTL of `_session_ttl_seconds` (5 minutes)
- Automatically cleans stale entries to prevent memory leaks

This design allows Agno agents to interact with MCP protocol services using fresh authentication tokens or user-specific headers for each execution context.

## Implementing MCP Tools in Agno Agents

### Basic Single-Server Integration

To enable an Agno agent to interact with MCP protocol services, instantiate `MCPTools` with the server endpoint and add it to the agent's tools list:

```python
from agno.tools.mcp import MCPTools
from agno.agent import Agent

# Initialize toolkit with HTTP transport and selective tool exposure

mcp_toolkit = MCPTools(
    url="http://localhost:8080/mcp",
    include_tools=["search", "summarize"],
    header_provider=lambda run_context: {
        "X-User-ID": run_context.user_id
    },
)

# Configure agent with MCP capabilities

research_agent = Agent(
    system_prompt="You are a research assistant with access to external search tools.",
    tools=[mcp_toolkit],
)

# Execute - toolkit connects lazily and exposes remote tools

response = await research_agent.run(
    user_message="Find recent articles about quantum computing."
)

```

The toolkit lazily establishes the connection during the agent's first execution cycle, calling `build_tools` to fetch available functions from the MCP server via `session.list_tools()`.

### Multi-Server Orchestration

For agents requiring access to multiple MCP endpoints, `MultiMCPTools` in [`libs/agno/agno/tools/mcp/multi_mcp.py`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/tools/mcp/multi_mcp.py) manages parallel connections. The constructor (lines 31-70) accepts lists of URLs and transports, while `get_session_for_run` (lines 66-104) tracks sessions using a composite key of `(run_id, server_idx)`.

```python
from agno.tools.mcp import MultiMCPTools

multi_toolkit = MultiMCPTools(
    urls=[
        "http://mcp-a.example.com/mcp",
        "http://mcp-b.example.com/mcp",
    ],
    urls_transports=["streamable-http", "streamable-http"],
    tool_name_prefix="server_b_",  # Namespace tools from second server

)

await multi_toolkit.connect()  # Explicit connection to all endpoints

```

## Tool Discovery and Execution Flow

Once connected, `MCPTools.build_tools` (lines 134-190) queries the MCP server and registers each remote tool as an Agno **`Function`**. The helper `get_entrypoint_for_tool` in [`libs/agno/agno/utils/mcp.py`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/utils/mcp.py) wraps MCP calls and converts responses into `ToolResult` objects, handling text, images, and embedded resources.

### Human-in-the-Loop and Control Flow

The toolkit supports advanced execution controls through constructor arguments processed in `MCPTools.__init__` (lines 54-61):

- **`requires_confirmation_tools`**: Forces user confirmation before execution
- **`external_execution_required_tools`**: Marks tools requiring external runtime
- **`stop_after_tool_call_tools`**: Halts agent execution after specific tool calls
- **`show_result_tools`**: Controls result visibility in agent outputs

These flags attach directly to the generated `Function` objects, enabling granular control over how Agno agents interact with sensitive MCP protocol services.

## Summary

- **Agno agents interact with MCP protocol services** through `MCPTools` and `MultiMCPTools` toolkit classes that extend the base `Toolkit` implementation in [`libs/agno/agno/tools/toolbox.py`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/tools/toolbox.py).
- **Connection management** supports `stdio`, `sse`, and `streamable-http` transports with automatic session caching and per-run header injection via `header_provider`.
- **Tool registration** occurs dynamically through `build_tools`, which converts MCP tool definitions into native Agno `Function` objects using `get_entrypoint_for_tool`.
- **Multi-server support** allows agents to simultaneously access multiple MCP endpoints with optional namespacing through `tool_name_prefix`.
- **HITL controls** enable confirmation requirements, external execution flags, and execution halting for specific remote tools.

## Frequently Asked Questions

### Can Agno agents use multiple MCP servers simultaneously?

Yes. The `MultiMCPTools` class manages connections to multiple MCP servers concurrently. According to the source code in [`libs/agno/agno/tools/mcp/multi_mcp.py`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/tools/mcp/multi_mcp.py), it maintains separate `ClientSession` instances for each endpoint indexed by `(run_id, server_idx)`, allowing agents to call tools from different servers within a single execution context.

### How does authentication work with MCP servers in Agno?

Authentication is handled through the `header_provider` parameter, which accepts a callable receiving the `RunContext`. As implemented in `MCPTools.get_session_for_run`, this function dynamically injects headers (such as `X-User-ID` or authorization tokens) into HTTP-based transports for each execution, with sessions cached for 5 minutes by default to balance performance and security.

### What transport protocols does Agno support for MCP integration?

Agno supports three transport methods: **`stdio`** for local subprocess communication, **`sse`** (Server-Sent Events), and **`streamable-http`** for HTTP-based endpoints. The transport is specified during `MCPTools` initialization and validated in the constructor located at [`libs/agno/agno/tools/mcp/mcp.py`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/tools/mcp/mcp.py) lines 28-74.

### Can I restrict which MCP tools an Agno agent can access?

Yes. Both `MCPTools` and `MultiMCPTools` accept `include_tools` and `exclude_tools` parameters that filter available functions during the `build_tools` phase. This filtering occurs after calling `session.list_tools()` on the MCP server but before registering functions with the agent, ensuring only approved tools are exposed.