AgentOS MCP Server

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

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.

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

Developer Resources

• MCP server configuration
• Connect local MCP clients with agno connect
• Runnable MCP examples

Describe and discover your server

Use MCPConfig.instructions to tell clients how to use your tools during MCP initialization. AgentOS publishes a Server Card at /mcp/server-card with the server identity, tool descriptions, and schemas. The card is public even when tool execution is authenticated; disable it with server_card=False when needed.

For several replicas, configure stateless MCP transport and shared application state. See AgentOS as MCP Server for discovery, authentication, transport settings, and client setup.