Skip to main content

Code

Secure the instance with OS_SECURITY_KEY. Every request to the API and to /mcp must then carry Authorization: Bearer <key>.
cookbook/05_agent_os/mcp_demo/mcp_server_example.py
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.anthropic import Claude
from agno.os import AgentOS
from agno.tools.websearch import WebSearchTools

# Setup the database
db = SqliteDb(db_file="tmp/agentos.db")

# Setup basic research agent
web_research_agent = Agent(
    id="web-research-agent",
    name="Web Research Agent",
    model=Claude(id="claude-sonnet-4-5"),
    db=db,
    tools=[WebSearchTools()],
    add_history_to_context=True,
    num_history_runs=3,
    add_datetime_to_context=True,
    enable_session_summaries=True,
    markdown=True,
)

# Setup AgentOS with MCP enabled
agent_os = AgentOS(
    description="Example app with MCP enabled",
    agents=[web_research_agent],
    mcp_server=True,  # This enables a LLM-friendly MCP server at /mcp
)

app = agent_os.get_app()

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

Define a Local Test Client

The client connects to /mcp with the security key in the Authorization header and drives the built-in tools.
test_client.py
import asyncio
from os import getenv
from uuid import uuid4

from agno.agent import Agent
from agno.db.in_memory import InMemoryDb
from agno.models.openai import OpenAIResponses
from agno.tools.mcp import MCPTools, StreamableHTTPClientParams

# Authenticate against the secured AgentOS with the security key
server_params = StreamableHTTPClientParams(
    url="http://localhost:7777/mcp",
    headers={"Authorization": f"Bearer {getenv('OS_SECURITY_KEY')}"},
)

session_id = f"session_{uuid4()}"


async def run_agent() -> None:
    async with MCPTools(
        transport="streamable-http", server_params=server_params, timeout_seconds=60
    ) as mcp_tools:
        agent = Agent(
            model=OpenAIResponses(id="gpt-5.5"),
            tools=[mcp_tools],
            instructions=[
                "You operate an AgentOS through its MCP tools.",
                "Call get_agentos_config first to discover the agents, teams, and workflows you can run.",
                "Use the run tools to delegate work, and the session tools to review past conversations.",
            ],
            user_id="john@example.com",
            session_id=session_id,
            db=InMemoryDb(),
            add_history_to_context=True,
            markdown=True,
        )

        await agent.aprint_response(
            input="Which agents do I have in my AgentOS?", stream=True, markdown=True
        )


if __name__ == "__main__":
    asyncio.run(run_agent())

Usage

1

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate
uv venv --python 3.12
.venv\Scripts\activate
2

Set Environment Variables

export ANTHROPIC_API_KEY=your_anthropic_api_key
export OPENAI_API_KEY=your_openai_api_key
export OS_SECURITY_KEY=your_security_key
3

Install dependencies

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

Run Server

python cookbook/05_agent_os/mcp_demo/mcp_server_example.py
5

Run Test Client

python test_client.py