AgentOS as MCP Server

Set mcp=True to serve an MCP server at /mcp alongside the REST API. ChatGPT and Claude connect as hosted custom connectors. Claude Code, Claude Desktop, Codex, and Cursor connect from your machine through Agno Connect.

mcp_server.py

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.anthropic import Claude
from agno.os import AgentOS

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

assistant = Agent(
    id="assistant",
    name="Assistant",
    model=Claude(id="claude-sonnet-4-5"),
    db=db,
    markdown=True,
)

agent_os = AgentOS(
    agents=[assistant],
    mcp=True,
)

app = agent_os.get_app()

if __name__ == "__main__":
    # MCP server available at http://localhost:7777/mcp
    agent_os.serve(app="mcp_server:app")

The MCP server needs fastmcp from the mcp extra. Building the app without it raises an ImportError. Install it along with the example’s other dependencies (the os extra for AgentOS and anthropic for the model):

pip install -U "agno[os,mcp]" anthropic

Connect MCP Clients

The server uses the Streamable HTTP transport. 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. Hosted apps cannot reach an AgentOS running only on localhost. Configure MCP OAuth on the AgentOS:

from agno.os import AgentOSBuiltinAuth

agent_os = AgentOS(
    agents=[assistant],
    db=db,
    mcp=True,
    mcp_auth=AgentOSBuiltinAuth.from_env(),
)

Set AGENTOS_URL to the exact public origin and set MCP_CONNECT_SECRET. Leave the connector’s optional OAuth client ID and client secret fields empty, then enter MCP_CONNECT_SECRET on the consent page. See the built-in OAuth example for the complete setup.

Local MCP Clients

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

uvx agno connect --url http://localhost:7777

Agno Connect discovers /mcp, configures each detected client, handles the configured authentication flow, and verifies the connection with an MCP handshake. Pass the AgentOS base URL without /mcp. Use the deployed base URL to connect local clients to a remote AgentOS. See agno connect for client selection, credentials, and project-scoped configuration. An Agno agent can operate the server through MCPTools. See Enable AgentOS MCP for a complete server and client pair.

Built-in Tools

The 8 built-in tools are scoped to what an LLM client needs to operate the instance. Session writes and memory CRUD stay on the REST API; register anything else as a custom tool.

Tool	Purpose	Key parameters
`get_agentos_config`	Discover the agents, teams, and workflows available to run, plus database IDs. Call first.	None
`run_agent`	Run an agent and return its response.	`agent_id`, `message`, optional `session_id` and `user_id`
`run_team`	Run a team. Same session and pause semantics as `run_agent`.	`team_id`, `message`, optional `session_id` and `user_id`
`run_workflow`	Run a workflow, reporting progress per step.	`workflow_id`, `message`, optional `session_id` and `user_id`
`continue_run`	Resume a `PAUSED` run after resolving its requirements (human-in-the-loop).	`run_id`, `session_id`, exactly one of `agent_id` / `team_id` / `workflow_id`, `requirements`
`cancel_run`	Request cancellation of a run.	`run_id`, `session_id`, exactly one of `agent_id` / `team_id` / `workflow_id`
`get_sessions`	List past sessions, newest first. Read-only.	`session_type`, `component_id`, `user_id`, `session_name`, `limit`, `page`, `db_id`
`get_session_runs`	Read a session’s history: each run’s input and answer. Pass `run_id` for that one run in full detail (complete transcript, events, and metrics).	`session_id`, optional `run_id`, `session_type`, `db_id`

Behavior shared by the run tools:

Omit session_id to start a fresh session; the new ID comes back in structuredContent. Pass a session_id from get_sessions to continue that conversation.
Long runs send MCP progress notifications: tool calls for agents and teams, step counts for workflows.
A result with status=PAUSED carries its unresolved requirements. Resolve them and pass them to continue_run.
db_id on the session tools is only needed when get_agentos_config lists multiple databases.

MCPConfig

Pass mcp=MCPConfig(...) to register custom tools, scope the built-ins, gate the server, and add transport protection:

from agno.os import AgentOS, MCPConfig

OWNER_IDS = {"owner@example.com"}

agent_os = AgentOS(
    agents=[assistant],
    mcp=MCPConfig(
        tools=[ask_workspace],                           # register custom tools
        exclude_tags={"session"},                        # drop the read-only session tools
        authorize=lambda user_id: user_id in OWNER_IDS,  # 401 non-owners before any tool runs
        allowed_hosts=["my-app.example.com"],            # DNS-rebinding protection
    ),
)

Option	Default	Description
`tools`	`None`	Publish custom callables, Agno tools/`Function`s, toolkits, agents, teams, workflows, or `component.as_tool(...)` entries. They share the `/mcp` mount, lifespan, and auth with the built-ins.
`default_tools`	`True`	Master switch for the 8 built-in tools. Set `False` to remove the default surface. `tools` must then contain at least one entry.
`lifecycle_tools`	`True`	Add component-scoped `continue_run` and `cancel_run` tools when `tools` publishes components.
`include_tags` / `exclude_tags`	`None`	Scope the built-ins by tag: `"core"` covers discovery, run, continue, and cancel tools; `"session"` covers the read-only session tools; `"lifecycle"` selects the continue and cancel pair.
`result_mode`	`"trimmed"`	How the run tools serialize results. See Result modes.
`authorize`	`None`	Per-call gate `fn(user_id) -> bool`. Runs after token verification; returning `False` rejects the request with 401 before any tool or model runs.
`allowed_hosts`	`None`	Host allowlist for DNS-rebinding protection. See Transport Security.
`allowed_origins`	`None`	Extra exact origins to allow when they are served from hosts outside `allowed_hosts`.
`middleware`	`None`	`starlette.middleware.Middleware` instances added to the MCP app.

A config with default_tools=False and no tools raises at construction, because it would mount a server with zero tools.

Result Modes

MCP tool results land in the consuming model’s context window, so the default keeps them small.

Mode	Result	Use when
`"trimmed"` (default)	Answer text plus generated media as MCP content blocks. `structuredContent` carries the mirrored answer, `run_id`, `session_id`, `status`, the owning component ID, and unresolved requirements when paused.	The client is an LLM frontend.
`"full"`	`structuredContent` is the run’s complete `to_dict()`, with media base64-encoded.	Programmatic clients that need the whole run object.

Custom Tools

from agno.tools import tool


@tool(
    name="ask_workspace",
    description="Ask the workspace agent a question and get an answer",
)
async def ask_workspace(question: str, user_id: str) -> str:
    response = await workspace_agent.arun(question, user_id=user_id)
    return response.content or ""

Declare a user_id parameter and AgentOS fills it with the authenticated caller’s ID (the JWT subject). The parameter is hidden from the client-facing tool schema, so callers cannot spoof it. Tools that need the full request can declare a FastMCP Context parameter, which FastMCP injects natively. Combine tools=[...] with default_tools=False to expose a focused tool surface instead of the built-ins. Publishing an agent, team, or workflow also adds its scoped lifecycle tools unless lifecycle_tools=False.

Authentication

AgentOS applies its configured authentication to the REST routes and MCP server. Without a security key, JWT authorization, or mcp_auth, /mcp accepts anonymous calls and restricts requests to localhost hosts by default. Configure authentication before deploying the endpoint.

Mode	Server setup	Client credential
Open local development	`mcp=True` with no authentication configured	None
Security key	`export OS_SECURITY_KEY="your-key"`	`Authorization: Bearer <security key>`
Service account token	Issue via `POST /service-accounts` (requires a database)	`Authorization: Bearer agno_pat_...`
JWT	`AgentOS(authorization=True, ...)`	`Authorization: Bearer <JWT>`
OAuth	`AgentOS(mcp=True, mcp_auth=...)`	OAuth access token

With authorization=True, each tool call is checked against the scopes of its equivalent REST route: run_agent requires the same scopes as POST /agents/{id}/runs, get_sessions the same as GET /sessions. See Security & Auth. The authorize gate on MCPConfig layers on top of authentication and can reject callers per request. It receives a verified user_id from JWT, service-account, or mcp_auth credentials. Open and security-key requests carry no user identity, so the gate receives None. Make sure your gate handles None, and return False to reject callers without an identity.

Transport Security

fastmcp’s built-in Host/Origin guard is disabled on /mcp, so MCPConfig.allowed_hosts acts as the transport guard instead:

Left unset, the default depends on your auth mode. A server with required authentication (a security key, JWT, or mcp_auth) skips host validation, because every request already has to prove itself. An open server gets localhost-only validation, since that is exactly the setup DNS rebinding attacks target.
When set, the request Host (and Origin, when present) must match your list or the localhost defaults (localhost, 127.0.0.1, [::1]). Anything else is rejected with 400 before it reaches the MCP machinery. *.example.com wildcard patterns are supported.

This is DNS-rebinding protection: it stops a malicious web page from driving an always-on local MCP server through a rebound DNS name. List only your deploy or tunnel host; localhost works out of the box.

Get Started

AgentOS

Example Usage

AgentOS as MCP Server

Connect MCP Clients

ChatGPT and Claude

Local MCP Clients

Built-in Tools

MCPConfig

Result Modes

Custom Tools

Authentication

Transport Security

Developer Resources

​Connect MCP Clients

​ChatGPT and Claude

​Local MCP Clients

​Built-in Tools

​MCPConfig

​Result Modes

​Custom Tools

​Authentication

​Transport Security

​Developer Resources

Connect MCP Clients

ChatGPT and Claude

Local MCP Clients

Built-in Tools

MCPConfig

Result Modes

Custom Tools

Authentication

Transport Security

Developer Resources