Skip to main content
Glama

Polyagent MCP

by execveat

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

-
security - not tested
A
license - permissive license
-
quality - not tested

local-only server

The server can only run on the client's local machine because it depends on local resources.

Enables any MCP-compatible client to use existing Claude Code agents from .claude/agents/ directories. Spawns agents in separate CLI sessions for better context optimization and performance across Codex, Gemini CLI, and other AI coding assistants.

  1. Why This Exists
    1. How It Works
      1. Installation
        1. Quick Start with uvx (Recommended)
        2. Local Development
      2. Configuration
        1. Codex
        2. Gemini CLI
        3. Environment Variables
      3. Usage
        1. Requirements
          1. License

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/execveat/polyagent-mcp'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server