isage-mcp — SAGE Unified MCP Server

One MCP server for all SAGE Zoo packages. Install once, configure once — get web search, RAG, agentic tools, and more in any MCP-compatible AI client.

Quick Start

# Install with all available zoo packages
pip install 'isage-mcp[all]'

# Start the server (stdio — for Claude Desktop)
sage-mcp

# Or HTTP/SSE — for VS Code Copilot, Cursor, etc.
sage-mcp --transport sse --port 9000

See which zoo packages are loaded:

sage-mcp --list-plugins
# Installed SAGE MCP plugins (1):
#   • sage_tools

Client Configuration

Claude Desktop

{
  "mcpServers": {
    "sage": {
      "command": "sage-mcp"
    }
  }
}

VS Code Copilot (settings.json)

"mcp": {
  "servers": {
    "sage": {
      "type": "sse",
      "url": "http://localhost:9000/sse"
    }
  }
}

Cursor / OpenHands / other MCP clients

Same pattern — use sage-mcp as the command (stdio) or point at the SSE URL.

Available Zoo Packages

How the Plugin System Works

sage-mcp supports two registration modes. New packages should use Mode 1.

Mode 1 — Auto (recommended, zero MCP code needed)

Add ONE line to pyproject.toml pointing at your tools module:

[project.entry-points."sage.mcp.modules"]
my_package = "my_package.tools"   # ← that's it

sage-mcp scans the module for all BaseTool subclasses and auto-wraps each one using the existing tool_name, tool_description, and execute() signature. No MCP-specific code is needed in the package at all.

Mode 2 — Explicit (for hand-crafted descriptions / advanced control)

Write a register_tools(mcp) function and declare it:

[project.entry-points."sage.mcp.tools"]
my_package = "my_package.mcp_server:register_tools"

def register_tools(mcp):
    @mcp.tool()
    async def my_tool(query: str, max_results: int = 5) -> list:
        """Custom hand-written description shown to the AI."""
        ...

If a package appears in both groups, explicit takes precedence (no double-registration).

What auto-wrapping does

For each BaseTool subclass found:

• tool_name → MCP tool name (normalised to snake_case)
• tool_description → MCP tool description shown to the AI
• execute(query: str, max_results: int = 5) → MCP parameter schema (type hints + defaults preserved)
• Async execute → async MCP tool; sync → sync tool

Architecture

sage-mcp (aggregator)
  │
  ├── sage.mcp.tools  (explicit — package writes register_tools)
  │      └── sage_tools → sage.tools.mcp_server:register_tools
  │
  └── sage.mcp.modules  (auto — no MCP code in package)
         └── sage_rag    → scan "sage.rag" for BaseTool subclasses
             sage_agentic → scan "sage.agentic" for BaseTool subclasses
             ...

If a package appears in both groups, the explicit path wins (no double-registration).

License

MIT — see LICENSE.