Reads agent definitions from Markdown files in the .claude/agents/ directory to configure available agents
Requires Python 3.10+ runtime environment for executing the MCP server
Uses TOML configuration format for Codex MCP server setup
Supports YAML configuration files for runner and agent configuration overrides
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:
Local Development
Clone and install for development:
Run locally with either:
Configuration
Codex
Add to your Codex configuration with a minimum 15-minute timeout:
For local development (if you've cloned the repo):
Important:
Use
tool_timeout_sec = 900
or higher. Lower timeouts will cause agent invocations to fail prematurelyThe
uvx
method automatically installs and updates from GitHubFor local development, replace
/path/to/polyagent-mcp
with your actual clone path
Gemini CLI
Add to your settings.json
:
For local development:
Important:
Timeout is in milliseconds:
900000
= 15 minutesFor 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 overridesPOLYAGENT_MCP_WORKSPACE
– working directory for agent executionPOLYAGENT_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/
:
List available agents: Check
resource://agents/manifest
or use your client's tool listingReview agent instructions: Read
agent://<agent-name>
before delegatingInvoke agents: Call the tool named after the agent (e.g.,
commit-agent
)
Example tool invocation:
Optional parameters:
runner
– force a specific CLI (codex
,claude
,gemini
)model
– runner-specific model aliastimeout_seconds
– extend timeout for long operations
Requirements
Python 3.10+
At least one of:
codex
,claude
, orgemini
CLI installedExisting
.claude/agents/
directory with agent definitions
License
MIT
This server cannot be installed
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.