Skip to content

MCP Integration

Native Model Context Protocol client. Connects sygen to external tool servers (databases, APIs, file systems) and exposes their tools to CLI providers.

Files

  • sygen_bot/mcp/client.py: MCPClient — single-server connection wrapper (stdio + SSE transports)
  • sygen_bot/mcp/manager.py: MCPManager — multi-server lifecycle, health monitoring, auto-restart
  • sygen_bot/mcp/tool_router.py: ToolRouter — bridges MCP tools into CLI provider config (--mcp-config)
  • sygen_bot/mcp/commands.py: /mcp Telegram command handler

Architecture

User → /mcp → MCPManager → MCPClient(s) → MCP Server(s)
                   ↓
              ToolRouter → .mcp.json → Claude CLI --mcp-config

MCPClient manages a single server connection via AsyncExitStack. Supports two transports: - stdio — launches a local process (command + args) - sse — connects to a remote HTTP SSE endpoint

MCPManager handles multiple servers: - Connects all enabled servers at startup - Caches tool listings for fast lookup - Runs a health check loop (30s interval) - Auto-restarts crashed servers (configurable per server)

ToolRouter generates a .mcp.json config file in Claude CLI format and injects --mcp-config into CLI arguments. Also provides get_tool_descriptions_for_prompt() for system prompt injection.

Configuration

{
  "mcp": {
    "enabled": true,
    "servers": [
      {
        "name": "filesystem",
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
        "enabled": true,
        "auto_restart": true,
        "startup_timeout_seconds": 10,
        "restart_delay_seconds": 2
      },
      {
        "name": "remote-api",
        "transport": "sse",
        "url": "http://localhost:8080/sse",
        "enabled": true
      }
    ]
  }
}

Telegram commands

Local agent (current agent's MCP)

  • /mcp — list connected servers and their tools
  • /mcp status — detailed health status (connected/disconnected, restart count, errors)
  • /mcp restart [server] — restart a specific server or all. Covers both Sygen MCPManager connections and CLI child MCP processes (killed via SIGTERM so the CLI auto-reconnects on next tool call)
  • /mcp refresh — re-fetch tools from all servers
  • /mcp help — command reference

Cross-agent (main agent only)

  • /mcp_restart <agent> [server] — restart MCP servers on a sub-agent (both Sygen connections and CLI child processes)
  • /mcp_status [agent] — show MCP health for a specific agent, or all agents with MCP enabled

These commands are registered only on the main agent when a supervisor is active.

Two-layer restart

/mcp restart and /mcp_restart operate on two layers simultaneously:

  1. Sygen MCPManager — disconnects and reconnects Sygen's own MCP client sessions
  2. CLI child processes — scans the process tree of active CLI processes for MCP server children (matched by patterns like mcp-server, mcp-atlassian, figma-developer-mcp, postman-mcp, etc.) and sends SIGTERM. The CLI auto-reconnects on the next tool call, preserving session context — no /new or bot restart needed

Installation

MCP requires the optional mcp dependency:

pip install sygen[mcp]

The mcp package is imported lazily — sygen runs without it, and shows a clear error when MCP is enabled but the package is missing.