MCP Demo

Define a FastAPI lifespan that connects MCPTools to the GitHub MCP server over stdio.

Run an Agent using our MCP integration in the Agno OS.

mcp_demo.py

"""This example shows how to run an Agent using our MCP integration in the Agno OS.

For this example to run you need:
- Create a GitHub personal access token following these steps:
    - https://github.com/modelcontextprotocol/servers/tree/main/src/github#setup
- Set the GITHUB_TOKEN environment variable: `export GITHUB_TOKEN=<Your GitHub access token>`
- Run: `uv pip install agno mcp openai` to install the dependencies
"""

from contextlib import asynccontextmanager
from os import getenv
from textwrap import dedent

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIChat
from agno.os import AgentOS
from agno.tools.mcp import MCPTools
from fastapi import FastAPI
from mcp import StdioServerParameters

# ---------------------------------------------------------------------------
# Create Example
# ---------------------------------------------------------------------------

agent_storage_file: str = "tmp/agents.db"


# MCP server parameters setup
github_token = getenv("GITHUB_TOKEN") or getenv("GITHUB_ACCESS_TOKEN")
if not github_token:
    raise ValueError("GITHUB_TOKEN environment variable is required")

server_params = StdioServerParameters(
    command="npx",
    args=["-y", "@modelcontextprotocol/server-github"],
)


# This is required to start the MCP connection correctly in the FastAPI lifecycle
@asynccontextmanager
async def lifespan(app: FastAPI):
    """Manage MCP connection lifecycle inside a FastAPI app"""
    global mcp_tools

    # Startuplogic: connect to our MCP server
    mcp_tools = MCPTools(server_params=server_params)
    await mcp_tools.connect()

    # Add the MCP tools to our Agent
    agent.tools = [mcp_tools]

    yield

    # Shutdown: Close MCP connection
    await mcp_tools.close()


agent = Agent(
    name="MCP GitHub Agent",
    instructions=dedent("""\
        You are a GitHub assistant. Help users explore repositories and their activity.

        - Use headings to organize your responses
        - Be concise and focus on relevant information\
    """),
    model=OpenAIChat(id="gpt-4o"),
    db=SqliteDb(db_file=agent_storage_file),
    update_memory_on_run=True,
    enable_session_summaries=True,
    add_history_to_context=True,
    num_history_runs=3,
    add_datetime_to_context=True,
    markdown=True,
)

# Setup our AgentOS app
agent_os = AgentOS(
    description="Example OS setup",
    agents=[agent],
)
app = agent_os.get_app()


# ---------------------------------------------------------------------------
# Run Example
# ---------------------------------------------------------------------------

if __name__ == "__main__":
    agent_os.serve(app="mcp_demo:app", reload=True)

Run the Example

1. Set up your virtual environment

   Mac

   uv venv --python 3.12
   source .venv/bin/activate
   

   uv venv --python 3.12
   .venv\Scripts\activate
   
2. Install dependencies

   uv pip install -U "agno[mcp,os]" openai
   
3. Prepare Node.js

   The MCP server runs with npx. Install Node.js, then verify the commands:

   node --version
   npx --version
   
4. Export environment variables

   Mac/Linux

   export GITHUB_TOKEN="your_github_token_here"
   export OPENAI_API_KEY="your_openai_api_key_here"
   

   $Env:GITHUB_TOKEN="your_github_token_here"
   $Env:OPENAI_API_KEY="your_openai_api_key_here"
   
5. Choose the GitHub token name

   Export GITHUB_TOKEN as shown above. GITHUB_ACCESS_TOKEN is accepted as a fallback name for the same personal access token.

6. Run the example

   Save the code above as mcp_demo.py, then run:

   python mcp_demo.py
   

Full source: cookbook/05_agent_os/advanced_demo/mcp_demo.py