Polyagent MCP

🚀 Polyagent MCP

The MCP server that integrates Claude Code agents into Codex, Gemini CLI, and other AI coding assistants. It allows any MCP-compatible client to leverage existing .claude/agents/ definitions without any additional configuration.

🚀 Quick Start

Polyagent MCP is a powerful tool that enables seamless integration of Claude Code agents into other AI coding assistants. Here's how you can get started quickly:

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:

⚠️ Important Note

• 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:

⚠️ Important Note

• 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

✨ Features

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).

💻 Usage Examples

Basic 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"
  }
}

Advanced Usage

Optional parameters:

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

📚 Documentation

Requirements

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

📄 License

MIT