execveat/polyagent-mcp

Polyagent MCP

MCP server that brings Claude Code agents to Codex, Gemini CLI and other AI coding assistants. Let any MCP-compatible client benefit from existing .claude/agents/ definitions, with zero additional configuration.

Why This Exists

Teams with Claude Code agents want colleagues on Codex or Gemini to reuse those same agents without porting anything. Polyagent MCP provides a zero-configuration experience for contributors using Codex or Gemini who might not have access to Claude Code, enabling the same agent-based workflows that Claude Code provides. It's designed as a drop-in feature for projects where there's already considerable thought put into designing Claude Code-optimized subagents.

How It Works

When you run this MCP server within Codex or Gemini, it spawns agents via separate CLI sessions, so they perform similarly to Claude Code agents. This provides the same benefits:

• Context optimization: The main process uses less context as agents are initialized with separate context and only pass back what's important—not all intermediary output and thinking tokens.
• Better performance: Each agent can be provided with its own knowledge and rules. Since it operates in a fresh session, this typically leads to way better prompt adherence compared to giving the same instructions to a single AI agent tasked with many responsibilities (single responsibility principle).

Installation

Quick Start with uvx (Recommended)

Run directly from GitHub without cloning:

# Default stdio transport
uvx --from git+https://github.com/execveat/polyagent-mcp polyagent-mcp

# HTTP transport on custom port
uvx --from git+https://github.com/execveat/polyagent-mcp polyagent-mcp --transport http --port 8000

Local Development

Clone and install for development:

git clone https://github.com/execveat/polyagent-mcp.git
cd polyagent-mcp
uv sync

Run locally with either:

# Using the console script
uv run polyagent-mcp

# Using fastmcp CLI (for development with auto-reload)
uv run fastmcp dev polyagent_mcp.server:mcp

Configuration

Codex

Add to your Codex configuration with a minimum 15-minute timeout:

[mcp_servers.agents]
command = "uvx"
args = ["--from", "git+https://github.com/execveat/polyagent-mcp", "polyagent-mcp"]
tool_timeout_sec = 900

For local development (if you've cloned the repo):

[mcp_servers.agents]
command = "uv"
args = ["--directory", "/path/to/polyagent-mcp", "run", "polyagent-mcp"]
tool_timeout_sec = 900

Important:

• Use tool_timeout_sec = 900 or higher. Lower timeouts will cause agent invocations to fail prematurely
• The uvx method automatically installs and updates from GitHub
• For local development, replace /path/to/polyagent-mcp with your actual clone path

Gemini CLI

Add to your settings.json:

{
  "mcpServers": {
    "agents": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/execveat/polyagent-mcp",
        "polyagent-mcp"
      ],
      "timeout": 900000
    }
  }
}

For local development:

{
  "mcpServers": {
    "agents": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/polyagent-mcp",
        "run",
        "polyagent-mcp"
      ],
      "timeout": 900000
    }
  }
}

Important:

• Timeout is in milliseconds: 900000 = 15 minutes
• For local development, replace /path/to/polyagent-mcp with your actual clone path

Environment Variables

Configure via environment variables (all optional):

• POLYAGENT_MCP_DIR – directory with agent Markdown files (default: .claude/agents)
• POLYAGENT_MCP_CONFIG – optional YAML/JSON file for runner/agent config overrides
• POLYAGENT_MCP_WORKSPACE – working directory for agent execution
• POLYAGENT_MCP_TIMEOUT – default timeout in seconds (default: 900)
• POLYAGENT_MCP_LOG_LEVEL – Python log level (default: INFO)
• POLYAGENT_MCP_DEBUG – enable FastMCP debug mode

Usage

Once configured, your MCP client will automatically discover all agents in .claude/agents/:

1. List available agents: Check resource://agents/manifest or use your client's tool listing
2. Review agent instructions: Read agent://<agent-name> before delegating
3. Invoke agents: Call the tool named after the agent (e.g., commit-agent)

Example tool invocation:

{
  "tool": "commit-agent",
  "arguments": {
    "task": "Review and commit the changes with an appropriate message",
    "context": "Fixed authentication bug in login flow"
  }
}

Optional parameters:

• runner – force a specific CLI (codex, claude, gemini)
• model – runner-specific model alias
• timeout_seconds – extend timeout for long operations

Requirements

• Python 3.10+
• At least one of: codex, claude, or gemini CLI installed
• Existing .claude/agents/ directory with agent definitions

License

MIT