polycode

A production-grade MCP (Model Context Protocol) server exposing 13 tools that let Claude Code (or any MCP client) control three AI coding agents — opencode, Gemini CLI, and Qwen Code — with full session continuity, auth checking, and structured error handling.

How It Works

Claude Code  (or Gemini CLI / Qwen Code)
    │  calls tools (MCP stdio)
    ▼
polycode server  (this package — auto-started by the MCP client)
    │
    ├── spawns opencode serve  →  talks to any of 182 models via opencode
    ├── invokes gemini CLI     →  Gemini API with session continuity
    └── invokes qwen CLI       →  Qwen API with session continuity

The MCP client (Claude Code, Gemini CLI, Qwen Code) auto-starts this server when the session begins. You never start it manually.

Related MCP server: MCP Coding Agents

Requirements

1. Python 3.11+

   python --version

2. opencode CLI — for the opencode_* tools

   npm install -g opencode-ai
   opencode --version  # should print 1.x.x

3. Gemini CLI — for the gemini_* tools (optional)

   npm install -g @google/gemini-cli
   gemini --version  # should print 0.36.x or higher

4. Qwen Code CLI — for the qwen_* tools (optional)

   npm install -g @qwen-code/qwen-code
   qwen --version  # should print 0.14.x or higher

5. A model provider for opencode — for the default ollama/qwen3.5:cloud, Ollama must be running locally. See Changing the Model for alternatives.

Installation

pip install polycode

Verify the CLI is accessible:

polycode --help

Windows note: If polycode is not found after install, find the full path with where polycode in PowerShell and use it in the MCP config below.

MCP Client Setup

All three supported MCP clients use the same config format — only the config file path differs.

macOS / Linux:

{
  "mcpServers": {
    "polycode": {
      "command": "polycode",
      "env": {
        "OPENCODE_DEFAULT_MODEL": "ollama/qwen3.5:cloud"
      }
    }
  }
}

Windows — use the full path to the binary. Find it by running where polycode in PowerShell, then paste the result as the command value:

{
  "mcpServers": {
    "polycode": {
      "command": "C:\\Users\\YourName\\AppData\\Local\\Programs\\Python\\Python313\\Scripts\\polycode.exe",
      "env": {
        "OPENCODE_DEFAULT_MODEL": "ollama/qwen3.5:cloud"
      }
    }
  }
}

Restart your MCP client after saving. All 13 tools appear automatically.

Tools Reference

opencode tools (8)

These tools control opencode — a multi-provider AI coding agent. Sessions are stateful — messages within a session share full context across any of the 180+ supported models.

opencode_start_session

Start a new opencode session. Must be called before opencode_send_message.

Returns:

{
  "session_id": "ses_2a29...",
  "model": "ollama/qwen3.5:cloud",
  "project_dir": "/path/to/project"
}

opencode_send_message

Send a prompt to an active session. Blocks until opencode finishes responding.

Returns:

{
  "response": "Here is the updated function...",
  "session_id": "ses_2a29...",
  "message_index": 1,
  "partial": false
}

opencode_get_history

Retrieve the full message history for a session (tracked in-process).

Returns:

{
  "session_id": "ses_2a29...",
  "messages": [
    {"role": "user", "content": "...", "timestamp": "2026-04-05T19:00:00Z"},
    {"role": "assistant", "content": "...", "timestamp": "2026-04-05T19:00:05Z"}
  ]
}

opencode_list_sessions

List all active opencode sessions.

Returns:

{
  "sessions": [
    {
      "session_id": "ses_2a29...",
      "model": "ollama/qwen3.5:cloud",
      "project_dir": "/path/to/project",
      "message_count": 4,
      "created_at": "2026-04-05T19:00:00Z"
    }
  ]
}

opencode_end_session

Close a session and free its resources.

Returns: {"session_id": "ses_2a29...", "closed": true}

opencode_list_models

List all models available in opencode across all authenticated providers, grouped by provider. Only providers you are authenticated/connected to will show models.

Returns:

{
  "models": ["ollama/qwen3.5:cloud", "openai/gpt-4o", "google/gemini-2.5-flash", "..."],
  "by_provider": {
    "ollama": ["ollama/qwen3.5:cloud", "..."],
    "openai": ["openai/gpt-4o", "..."],
    "google": ["google/gemini-2.5-flash", "..."]
  },
  "total": 182,
  "default_model": "ollama/qwen3.5:cloud"
}

opencode_set_model

Change the default model for new sessions (takes effect immediately for all subsequent opencode_start_session calls).

Returns: {"previous_model": "ollama/...", "new_model": "openai/gpt-4o"}

opencode_shutdown

Gracefully stop the opencode server and close all active sessions.

Returns: {"stopped": true, "sessions_closed": 2}

Gemini CLI tools (4)

These tools invoke the gemini CLI directly. Sessions are persisted to disk by the CLI — pass session_id to continue a conversation across calls.

Requires: gemini CLI installed and authenticated (OAuth or GEMINI_API_KEY).

gemini_check_auth

Check whether the Gemini CLI is authenticated before making prompt calls.

Returns:

{
  "authenticated": true,
  "method": "api_key_or_oauth",
  "detail": "OK — model: gemini-2.5-flash-lite",
  "suggestion": ""
}

If authenticated is false, suggestion tells you how to fix it.

gemini_prompt

Send a prompt to Gemini CLI. Returns the response and a session_id that can be passed back to continue the conversation.

Returns:

{
  "response": "The word you asked me to remember is BLUEBIRD.",
  "model": "gemini-2.5-flash-lite",
  "session_id": "69cfc177-319c-484c-9..."
}

Multi-turn example:

# Turn 1 — new session
gemini_prompt(prompt="Remember the word BLUEBIRD")
→ { session_id: "69cfc177-..." }

# Turn 2 — continue session
gemini_prompt(prompt="What word did I ask you to remember?", session_id="69cfc177-...")
→ { response: "BLUEBIRD" }

gemini_list_sessions

List saved Gemini CLI sessions for the current project.

Returns:

{
  "sessions": [
    {"raw": "0: [2026-04-05] Remember the word BLUEBIRD"},
    {"raw": "1: [2026-04-05] Explain the polycode architecture"}
  ]
}

Qwen Code CLI tools (3)

These tools invoke the qwen CLI directly. Sessions are persisted to disk by the CLI — pass session_id to continue a conversation across calls.

Requires: qwen CLI installed and authenticated (qwen auth qwen-oauth or qwen auth coding-plan).

qwen_check_auth

Check whether the Qwen Code CLI is authenticated before making prompt calls.

Returns:

{
  "authenticated": true,
  "method": "qwen-oauth",
  "detail": "=== Authentication Status ===\n✓ Authentication Method: Qwen OAuth\n  Type: Free tier",
  "suggestion": ""
}

If authenticated is false, suggestion tells you the exact command to run.

qwen_prompt

Send a prompt to Qwen Code CLI. Returns the response and a session_id that can be passed back to continue the conversation.

Returns:

{
  "response": "The word you asked me to remember was REDPANDA.",
  "model": "coder-model",
  "session_id": "ead03e7a-afff-4ccd-a..."
}

Multi-turn example:

# Turn 1 — new session
qwen_prompt(prompt="Remember the word REDPANDA")
→ { session_id: "ead03e7a-..." }

# Turn 2 — continue session
qwen_prompt(prompt="What word did I ask you to remember?", session_id="ead03e7a-...")
→ { response: "REDPANDA" }

Changing the opencode Model

The model format is provider/model-name. Set it via env var:

"env": {
  "OPENCODE_DEFAULT_MODEL": "openai/gpt-4o"
}

Or call opencode_set_model at runtime. Call opencode_list_models to see all 182 available models across your connected providers.

Common models:

Configuration

Error Handling

Every tool always returns a structured response — never a raw exception:

{
  "error": "OpencodeBinaryNotFoundError",
  "message": "gemini CLI not found on PATH. Install: npm install -g @google/gemini-cli",
  "detail": {},
  "recoverable": false,
  "suggestion": "Install opencode via: npm install -g opencode-ai"
}

Common errors:

Troubleshooting

"polycode not found" on Windows

Use the full path in your MCP config. Find it with:

where polycode

opencode server times out on startup

Cloud models do a network handshake on first use. Increase the timeout:

"env": { "OPENCODE_STARTUP_TIMEOUT": "30" }

Tools appear but calls hang

On Windows, subprocesses can inherit a blocked stdin from the MCP stdio pipe. This package sets stdin=DEVNULL on all subprocesses — ensure you are on polycode >= 0.1.0.

gemini_prompt or qwen_prompt returns an auth error

Run the auth check first:

• gemini_check_auth → reads suggestion field for the fix

• qwen_check_auth → reads suggestion field for the fix

Then authenticate interactively (gemini or qwen auth qwen-oauth) and retry.

Running Tests

git clone https://github.com/h19overflow/polycode
cd polycode
pip install -e ".[dev]"

# Unit tests — no CLIs required
pytest tests/ --ignore=tests/test_integration.py -v

# Integration tests — requires opencode + ollama
pytest tests/test_integration.py -m integration -v

Contributing

1. Fork the repo

2. pip install -e ".[dev]"

3. Write tests first (TDD)

4. pytest tests/ --ignore=tests/test_integration.py must pass

5. pyright . must show 0 errors

6. Open a PR

License

MIT — see LICENSE