> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol (MCP)

> Connect agents to external systems through the standardized MCP interface.

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) enables Agents to interact with external systems through a standardized interface.
You can connect your Agents to any MCP server, using Agno's MCP integration.

```bash theme={null}
pip install "agno[mcp]" anthropic openai
```

> [!NOTE]
>
> Local stdio servers require their own command runtimes. Install [Node.js](https://nodejs.org/en/download) for the `npx` filesystem example and install [uv](https://docs.astral.sh/uv/getting-started/installation/) for the `uvx` Git examples below.

Below is a simple example that connects an Agent to the Agno MCP server:

```python theme={null}
from agno.agent import Agent
from agno.models.anthropic import Claude
from agno.tools.mcp import MCPTools

# Create the Agent
agno_agent = Agent(
    name="Agno Agent",
    model=Claude(id="claude-sonnet-4-5"),
    # Add the Agno MCP server to the Agent
    tools=[MCPTools(transport="streamable-http", url="https://docs.agno.com/mcp")],
)
```

## The Basic Flow

**1. Find the MCP server you want to use**

You can use any working MCP server. To see some examples, you can check [this GitHub repository](https://github.com/modelcontextprotocol/servers), by the maintainers of the MCP themselves.

**2. Initialize the MCP integration**

Initialize the `MCPTools` class and connect to the MCP server.
The recommended way to define the MCP server is to use the `command` or `url` parameters.
With `command`, you can pass the command used to run the MCP server you want. With `url`, you can pass the URL of the running MCP server you want to use.

For example, to connect to the Agno documentation MCP server, you can do the following:

```python theme={null}
from agno.tools.mcp import MCPTools

# Initialize and connect to the MCP server
mcp_tools = MCPTools(transport="streamable-http", url="https://docs.agno.com/mcp")
await mcp_tools.connect()
```

**3. Provide the MCPTools to the Agent**

When initializing the Agent, pass the `MCPTools` instance in the `tools` parameter. Remember to close the connection when you're done.

The agent will now be ready to use the MCP server:

```python theme={null}
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.mcp import MCPTools

# Initialize and connect to the MCP server
mcp_tools = MCPTools(url="https://docs.agno.com/mcp")
await mcp_tools.connect()

try:
    # Setup and run the agent
    agent = Agent(model=OpenAIResponses(id="gpt-5.2"), tools=[mcp_tools])
    await agent.aprint_response("Tell me more about MCP support in Agno", stream=True)
finally:
    # Always close the connection when done
    await mcp_tools.close()
```

### Example: Filesystem Agent

Here's a filesystem agent that uses the [Filesystem MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) to explore and analyze files:

```python filesystem_agent.py theme={null}
import asyncio
from pathlib import Path
from textwrap import dedent

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.mcp import MCPTools


async def run_agent(message: str) -> None:
    """Run the filesystem agent with the given message."""

    file_path = "<path to the directory you want to explore>"

    # Initialize and connect to the MCP server to access the filesystem
    mcp_tools = MCPTools(
        command=f"npx -y @modelcontextprotocol/server-filesystem {file_path}",
        include_tools=[
            "list_allowed_directories",
            "list_directory",
            "read_file",
        ],
    )
    await mcp_tools.connect()

    try:
        agent = Agent(
            model=OpenAIResponses(id="gpt-5.2"),
            tools=[mcp_tools],
            instructions=dedent("""\
                You are a filesystem assistant. Help users explore files and directories.

                - Navigate the filesystem to answer questions
                - Use the list_allowed_directories tool to find directories that you can access
                - Provide clear context about files you examine
                - Use headings to organize your responses
                - Be concise and focus on relevant information\
            """),
            markdown=True,
        )

        # Run the agent
        await agent.aprint_response(message, stream=True)
    finally:
        # Always close the connection when done
        await mcp_tools.close()


# Example usage
if __name__ == "__main__":
    # Basic example - exploring project license
    asyncio.run(run_agent("What is the license for this project?"))
```

## Connecting your MCP server

### Using `connect()` and `close()`

It is recommended to use the `connect()` and `close()` methods to manage the connection lifecycle of the MCP server.

```python theme={null}
mcp_tools = MCPTools(command="uvx mcp-server-git")
await mcp_tools.connect()
```

After you're done, you should close the connection to the MCP server.

```python theme={null}
await mcp_tools.close()
```

> [!TIP]
>
> This is the recommended way to manage the connection lifecycle of the MCP server when using `Agent` or `Team` instances.

### Automatic Connection Management

If you pass the `MCPTools` instance to the `Agent` or `Team` instances without first calling `connect()`, the connection will be managed automatically.

For example:

```python theme={null}
mcp_tools = MCPTools(command="uvx mcp-server-git")
agent = Agent(model=OpenAIResponses(id="gpt-5.2"), tools=[mcp_tools])
await agent.aprint_response("What is the license for this project?", stream=True)  # The connection is established and closed on each run.
```

> [!NOTE]
>
> Here the connection to the MCP server (in the case of hosted MCP servers) is established and closed on each run.
> Additionally the list of available tools is refreshed on each run.
>
> This has an impact on performance and is not recommended for production use.

### Using Async Context Manager

Use `MCPTools` as an async context manager for automatic resource cleanup:

```python theme={null}
async with MCPTools(command="uvx mcp-server-git") as mcp_tools:
    agent = Agent(model=OpenAIResponses(id="gpt-5.2"), tools=[mcp_tools])
    await agent.aprint_response("What is the license for this project?", stream=True)
```

This pattern automatically handles connection and cleanup, but the explicit `.connect()` and `.close()` methods provide more control over connection lifecycle.

### Automatic Connection Management in AgentOS

When using MCPTools within AgentOS, the lifecycle is automatically managed. No need to manually connect or disconnect the `MCPTools` instance. This does not automatically refresh connections. You can use [`refresh_connection`](#connection-refresh) to do so.

See the [AgentOS + MCPTools](https://agno-v2.mintlify.site/agent-os/mcp/tools.md) page for more details.

> [!TIP]
>
> This is the recommended way to manage the connection lifecycle of the MCP server when using `AgentOS`.

## Connection Refresh

Set `refresh_connection` on an `MCPTools` instance to check its MCP session before each run. An unhealthy session is reconnected, then the available tools are refreshed.

```python theme={null}
mcp_tools = MCPTools(command="uvx mcp-server-git", refresh_connection=True)
await mcp_tools.connect()

agent = Agent(model=OpenAIResponses(id="gpt-5.2"), tools=[mcp_tools])
await agent.aprint_response("What is the license for this project?", stream=True)  # The connection is checked and tools are refreshed on each run.

await mcp_tools.close()
```

### How it works

* When you call the `connect()` method, a new session is established with the MCP server. If that server becomes unavailable, that connection is closed and a new one has to be established.
* If you set `refresh_connection` to `True`, each time the agent is run the connection to the MCP server is checked and re-established if needed, and the list of available tools is then refreshed.
* This is particularly useful for hosted MCP servers that are prone to restarts or that often change their schema or list of tools.
* It is recommended to only use this when you manually manage the connection lifecycle of the MCP server, or when using agents/teams with [`MCPTools` in `AgentOS`](https://agno-v2.mintlify.site/agent-os/mcp/tools).

## Transports

Transports define how MCP messages are sent and received. Agno supports the two [standard MCP transports](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports) plus deprecated standalone SSE compatibility:

* [stdio](https://agno-v2.mintlify.site/tools/mcp/transports/stdio.md) for local subprocess servers
* [Streamable HTTP](https://agno-v2.mintlify.site/tools/mcp/transports/streamable_http.md) for remote servers
* [Standalone SSE](https://agno-v2.mintlify.site/tools/mcp/transports/sse.md) for legacy servers. This transport is deprecated in Agno v3.0.4 and will be removed in a future release.

> [!NOTE]
>
> The stdio transport is the default in `MCPTools`. Use Streamable HTTP for new remote servers.

## Best Practices

1. **Resource Cleanup**: Always close MCP connections when done to prevent resource leaks:

```python theme={null}
mcp_tools = MCPTools(command="uvx mcp-server-git")
await mcp_tools.connect()

try:
    # Your agent code here
    pass
finally:
    await mcp_tools.close()
```

2. **Error Handling**: Always include proper error handling for MCP server connections and operations.

3. **Clear Instructions**: Provide clear and specific instructions to your agent:

```python theme={null}
instructions = """
You are a filesystem assistant. Help users explore files and directories.
- Navigate the filesystem to answer questions
- Use the list_allowed_directories tool to find accessible directories
- Provide clear context about files you examine
- Be concise and focus on relevant information
"""
```

## Developer Resources

* See how to use MCP with AgentOS [here](https://agno-v2.mintlify.site/agent-os/mcp/tools.md).
* Find examples of Agents that use MCP [here](https://agno-v2.mintlify.site/tools/mcp/usage/airbnb.md).
* Find a collection of MCP servers [here](https://github.com/modelcontextprotocol/servers).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.