Sagewai MCP Server

This guide shows you how to expose your Sagewai agents as tools that MCP clients — Claude Code, Cursor, and others — can call directly.

Prerequisites:

• Sagewai installed: pip install sagewai
• Gateway running: sagewai admin serve or make dev-native APP=admin
• API token (optional): sagewai token create --agent <name> --scopes chat

The MCP agent server uses the built-in McpServer from the SDK. You do not need to install the external mcp package for basic use.

How it works

The server connects to your running Sagewai gateway, discovers registered agents, and exposes each one as an MCP tool. When a client invokes a tool, the server forwards the call to the corresponding agent via the OpenAI-compatible API and returns the response.

MCP Client (Claude Code, Cursor, ...)
    |
    v
sagewai.mcp.agent_server  (stdio transport)
    |
    v
POST /v1/chat/completions  { "model": "<agent>", ... }
    |
    v
Sagewai Gateway  -->  AgentRegistry  -->  Agent response

Setup

Claude Code

Add the server to your project's .claude/settings.json or to ~/.claude/settings.json for global access:

{
  "mcpServers": {
    "sagewai": {
      "command": "python",
      "args": ["-m", "sagewai.mcp.agent_server"],
      "env": {
        "SAGEWAI_GATEWAY_URL": "http://localhost:8000",
        "SAGEWAI_GATEWAY_TOKEN": "your-token"
      }
    }
  }
}

Cursor

Add the same configuration to your Cursor MCP settings (.cursor/mcp.json or the settings UI).

Command line

Run the server directly without any config file:

python -m sagewai.mcp.agent_server \
    --gateway-url http://localhost:8000 \
    --token your-token

Or use environment variables:

export SAGEWAI_GATEWAY_URL=http://localhost:8000
export SAGEWAI_GATEWAY_TOKEN=your-token
python -m sagewai.mcp.agent_server

Usage

Once configured, each registered agent appears in Claude Code as a tool named sagewai_chat_{agent_name}. Call it like any other tool:

User: Use the knowledge agent to find what we decided about the database migration.

Claude: I'll query your Sagewai knowledge agent.
[Calls tool: sagewai_chat_knowledge_agent]
Result: "Based on the meeting notes from March 15, the team decided to
migrate from MySQL to PostgreSQL with a phased rollout..."

Available tools

The server discovers agents from the gateway at startup. Each agent becomes a tool with a single message parameter:

The input schema for every tool is:

{
  "message": "Your question or instruction for the agent"
}

Programmatic usage

Create the server from Python when you need more control — for example, to embed it into a larger service or to expose it over HTTP instead of stdio:

import asyncio
from sagewai.mcp.agent_server import create_agent_server

async def main():
    server = await create_agent_server(
        gateway_url="http://localhost:8000",
        token="your-token",
    )
    # Run over stdio for MCP clients
    await server.run_stdio()

    # Or get an ASGI app for HTTP hosting
    app = server.as_asgi_app()

asyncio.run(main())

Troubleshooting

No tools appear

Check that the gateway is running and that agents are registered:

curl http://localhost:8000/v1/models \
  -H "Authorization: Bearer your-token"

The response should include a list of agent IDs.

Authentication errors

Verify your token is still valid:

sagewai token list

If you are running without authentication, remove the SAGEWAI_GATEWAY_TOKEN environment variable entirely.

Connection refused

Confirm the gateway is listening at the URL in SAGEWAI_GATEWAY_URL. The default is http://localhost:8000. If your admin backend runs on a different port, update the variable to match.

Timeout on large responses

The server applies a 120-second timeout to agent calls. For agents that take longer, increase the timeout in the gateway configuration or break the task into smaller requests.