AgentOS MCP Server

Set mcp=True to serve an MCP endpoint at /mcp alongside the AgentOS REST API.

mcp_server.py

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS

db = SqliteDb(db_file="agentos.db")

assistant = Agent(
    id="assistant",
    model=OpenAIResponses(id="gpt-5.5"),
    db=db,
    add_history_to_context=True,
)

agent_os = AgentOS(
    agents=[assistant],
    db=db,
    mcp=True,
)
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app=app)

Install the AgentOS, MCP, and model dependencies:

uv pip install -U "agno[os,mcp,openai]"

Set OPENAI_API_KEY, then run python mcp_server.py. The MCP endpoint is available at http://localhost:7777/mcp. The default MCP surface provides eight tools for discovering registered components, running agents, teams, and workflows, continuing or cancelling paused runs, and reading session history.

Publish Selected Components

Use MCPConfig to publish selected components or custom callables as MCP tools:

from agno.os import AgentOS, MCPConfig

agent_os = AgentOS(
    agents=[assistant],
    mcp=MCPConfig(
        default_tools=False,
        tools=[
            assistant.as_tool(
                name="assistant",
                description="Answer questions with the registered assistant",
            ),
        ],
    ),
)

Published components use the same AgentOS execution, persistence, and authorization paths as the built-in run tools. Lifecycle tools remain available by default so MCP clients can continue or cancel paused runs.

Connect MCP Clients

Choose the connection method based on where the client runs.

Client	Connection method	URL
ChatGPT and Claude	Custom connector	Public MCP endpoint ending in `/mcp`
Claude Code, Claude Desktop, Codex, and Cursor	Agno Connect on your machine	AgentOS base URL

ChatGPT and Claude

Deploy AgentOS to a public HTTPS URL. In ChatGPT or Claude, open Settings → Connectors → Add custom connector and enter:

https://<your-domain>/mcp

The endpoint must be publicly reachable over HTTPS. For ChatGPT and Claude, a secured MCP endpoint must use OAuth. Their connector UIs do not accept bearer tokens. When using AgentOSBuiltinAuth, set AGENTOS_URL to the exact public origin, leave the optional OAuth client ID and client secret fields empty, then enter MCP_CONNECT_SECRET on the consent page. See the built-in OAuth example.

Local MCP Clients

Run Agno Connect on the machine where Claude Code, Claude Desktop, Codex, or Cursor is installed:

uvx agno connect --url https://<your-domain>

Agno Connect discovers the MCP endpoint, updates each detected client’s configuration, and verifies the connection with an MCP handshake. Pass the AgentOS base URL without /mcp. The command also works with a local AgentOS, such as http://localhost:7777.

Choose the MCP Direction

Task	API	Guide
Expose AgentOS to MCP clients	`AgentOS(mcp=...)`	AgentOS as an MCP server
Give an agent access to external MCP servers	`MCPTools`	MCPTools within AgentOS

Welcome

Get Started

Features

Use Cases

AgentOS MCP Server

Publish Selected Components

Connect MCP Clients

ChatGPT and Claude

Local MCP Clients

Choose the MCP Direction

Developer Resources

​Publish Selected Components

​Connect MCP Clients

​ChatGPT and Claude

​Local MCP Clients

​Choose the MCP Direction

​Developer Resources

Publish Selected Components

Connect MCP Clients

ChatGPT and Claude

Local MCP Clients

Choose the MCP Direction

Developer Resources