README.md•5 kB
# 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:
```bash
# 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:
```bash
git clone https://github.com/execveat/polyagent-mcp.git
cd polyagent-mcp
uv sync
```
Run locally with either:
```bash
# 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**:
```toml
[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):
```toml
[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`:
```json
{
"mcpServers": {
"agents": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/execveat/polyagent-mcp",
"polyagent-mcp"
],
"timeout": 900000
}
}
}
```
**For local development**:
```json
{
"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:
```json
{
"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