Use WorkOS AuthKit for MCP OAuth

Keep AgentOS as the MCP resource server while WorkOS AuthKit owns login, consent, and token issuance. Configure AuthKit to issue AgentOS resource scopes such as config:read and agents:run.

oauth_authkit.py

"""
Use WorkOS AuthKit for MCP OAuth
================================

Keep AgentOS as the MCP resource server while WorkOS AuthKit owns login,
consent, and token issuance. Configure AuthKit to issue AgentOS resource
scopes such as ``config:read`` and ``agents:run``.

Prerequisites: OPENAI_API_KEY, AUTHKIT_DOMAIN, and public AGENTOS_URL
Run: .venvs/demo/bin/python cookbook/05_agent_os/14_mcp/oauth_authkit.py
Try: Inspect GET /.well-known/oauth-protected-resource/mcp
"""

import os

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from fastmcp.server.auth.providers.workos import AuthKitProvider

# ---------------------------------------------------------------------------
# Create an AuthKit-protected AgentOS
# ---------------------------------------------------------------------------

db = SqliteDb(
    id="mcp-oauth-authkit-db",
    db_file="tmp/mcp_oauth_authkit.db",
)

authkit_agent = Agent(
    id="authkit-assistant",
    name="AuthKit Assistant",
    model=OpenAIResponses(id="gpt-5.5"),
    db=db,
    instructions="Answer authenticated users concisely.",
)

mcp_auth = AuthKitProvider(
    authkit_domain=os.environ["AUTHKIT_DOMAIN"],
    base_url=os.environ["AGENTOS_URL"],
)

agent_os = AgentOS(
    id="mcp-oauth-authkit-os",
    description="AgentOS using WorkOS AuthKit for MCP OAuth.",
    db=db,
    agents=[authkit_agent],
    mcp=True,
    mcp_auth=mcp_auth,
)
app = agent_os.get_app()

# ---------------------------------------------------------------------------
# Run AuthKit AgentOS
# ---------------------------------------------------------------------------

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

Run the Example

Set up your virtual environment

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

Install dependencies

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

Export environment variables

export AGENTOS_URL="https://agentos.example.com"
export AUTHKIT_DOMAIN="https://tenant.authkit.app"
export OPENAI_API_KEY="your_openai_api_key_here"

Configure the authorization provider

Enable Dynamic Client Registration in your AuthKit tenant and register the public https://agentos.example.com/mcp resource indicator. Emit AgentOS scopes such as config:read, agents:run, teams:run, workflows:run, and sessions:read in the token’s scope or scp claim. Ordinary openid, profile, and email scopes alone do not authorize AgentOS tool calls. Set AUTHKIT_DOMAIN to your tenant origin, such as https://tenant.authkit.app, and AGENTOS_URL to the externally reachable HTTPS AgentOS origin.

Run the example

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

python oauth_authkit.py

Connect an MCP client

Expose the running app at the exact HTTPS origin configured in AGENTOS_URL, then add that origin’s /mcp endpoint to your connector. Inspect /.well-known/oauth-protected-resource/mcp on that origin if discovery fails. Sign in through AuthKit and grant the requested resource scopes.

Full source: cookbook/05_agent_os/14_mcp/oauth_authkit.py