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

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, 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:

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

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 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.
• 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}