Coeus AI MCP

Coeus is a provider-neutral MCP server for local AI-assisted engineering workflows. It gives MCP-capable clients one stable coeus_* tool surface for project intake, model routing, code review, debugging, testing, docs drift checks, release readiness, design review, and multi-provider verification.

The current registry contains 55 tools. Provider selection is separate from workflow naming, so clients can keep the same MCP calls while choosing an OAuth-backed CLI or a direct API provider.

What Coeus Provides

• A standard MCP stdio server named coeus.

• 55 provider-neutral coeus_* tools for common developer workflows.

• Runtime provider health, capability, readiness, and catalog reporting.

• Automatic provider routing with bounded fallback when auto-selected providers are unavailable.

• Multi-provider verification with explicit consensus limits.

Install

Requirements:

• Python 3.11 or newer.

• At least one authenticated provider: an OAuth CLI session for agy, codex, or claude, or a direct API key for deepseek, alibaba, or openrouter.

git clone https://github.com/soryko/coeus-mcp.git
cd coeus-mcp
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"

For centralized local setup, place the three direct provider keys and other Coeus settings in the repository-root .env file. Coeus loads that file when configuration is initialized; variables already supplied by the process take precedence. The file is gitignored and must not be committed.

Start from the included template:

cp .env.example .env

COEUS_DEEPSEEK_API_KEY=
COEUS_ALIBABA_API_KEY=
COEUS_OPENROUTER_API_KEY=
COEUS_DEFAULT_PROVIDER=auto

The agy, codex, and claude adapters use subscriptions already authenticated in their local CLIs. No API key is required or accepted for these adapters. Run the interactive login once as the same user that runs Coeus:

agy login
codex login
claude login

OAuth tokens remain in the CLI credential stores and must not be copied into .env. Only COEUS_DEEPSEEK_API_KEY, COEUS_ALIBABA_API_KEY, and COEUS_OPENROUTER_API_KEY are direct API credentials read from .env.

Verify the server locally:

python - <<'PY'
from mcp_server import CoeusMCPServer

server = CoeusMCPServer()
print(server.call_tool("coeus_healthcheck", {}))
print(server.call_tool("coeus_capabilities", {})["providers"])
PY

The console script used by MCP clients is:

./.venv/bin/coeus-ai

MCP Client Configuration

Use an absolute path to coeus-ai. Desktop clients often launch without your shell profile, so relying on PATH is brittle.

{
  "mcpServers": {
    "coeus": {
      "command": "/absolute/path/to/coeus-ai-mcp/.venv/bin/coeus-ai",
      "env": {
        "COEUS_DEFAULT_PROVIDER": "auto"
      }
    }
  }
}

After connecting, ask your agent:

Use coeus_healthcheck and summarize which providers are ready.

More client-specific examples live in docs/integrations.md.

Providers, catalogs, and routing

Coeus providers implement the same contract:

• healthcheck(probe_network=False)

• list_models()

• ask(prompt, model, temperature, max_tokens)

COEUS_DEFAULT_PROVIDER=auto is the recommended default. In automatic mode, Coeus selects ready, configured, capability-compatible candidates. A runtime authentication, availability, timeout, or transport failure may trigger bounded fallback.

Strict provider IDs (agy, codex, claude, deepseek, alibaba, and openrouter) request one provider and never fall back to another. Direct-key preference aliases (deepseek_key, alibaba_key, and openrouter_key) put one provider first but remain fallback-eligible. Supplying an explicit model disables fallback, including when provider="auto".

When fallback occurs, inspect provider, model, fallback_from, fallback_reason, and fallback_attempts in the result. coeus_route reports the planned route without calling a provider; coeus_ask executes it.

Call coeus_list_models for the authoritative provider inventory. A provider entry contains status, models, and complete. Model records normalize provider, id, raw_id, capabilities, source, discovered_at, availability, available, deprecated, and provider-specific metadata. Catalog probes are bounded and cached for COEUS_PROVIDER_CATALOG_TTL (60 seconds by default); incomplete or stale catalogs are not treated as ready routing evidence.

coeus_healthcheck reports configured, ready, default_model, and auth details. OAuth providers include auth_mode, oauth, command_available, and resolved_path; direct providers include api_key_configured. When a catalog was observed, health also includes catalog_status, catalog_source, catalog_loaded_at, catalog_age_seconds, catalog_complete, and catalog_stale. For the normalized, secret-safe view, use coeus_runtime_diagnostics; its nested readiness contains configured, reachable, direct_key, oauth, catalog, and ready.

coeus_multi_model_verify executes one strict provider/model attempt per selected entry. It reports consensus only when at least two distinct provider/model responses are substantive.

Complete tool surface

The registry exposes exactly 55 provider-neutral tools:

coeus_healthcheck, coeus_capabilities, coeus_list_models, coeus_runtime_diagnostics, coeus_stats, coeus_route, coeus_ask, coeus_project_intake, coeus_review_bundle, coeus_counterfactual_review, coeus_debug_playbook, coeus_test_strategy, coeus_docs_drift_check, coeus_release_readiness, coeus_multi_model_verify, coeus_wildcard, coeus_design_review_bundle, coeus_version, coeus_summarize, coeus_eval_plan, coeus_review_code, coeus_verify_solution, coeus_thinkdeep, coeus_project_task_plan, coeus_second_opinion, coeus_workflow_automation_plan, coeus_frontend_design_brief, coeus_frontend_taste_direction, coeus_css_component_creator, coeus_ui_asset_sources, coeus_static_asset_plan, coeus_critical_debate, coeus_analyze_codebase, coeus_codebase_map, coeus_design_review, coeus_start_conversation, coeus_continue_conversation, coeus_list_conversations, coeus_clear_conversation, coeus_ai_collaboration, coeus_extract_structured, coeus_git_diff_review, coeus_content_comparison, coeus_review_pr, coeus_web_search, coeus_web_fetch, coeus_image_generate, coeus_generate_tests, coeus_refactor_code, coeus_explain_code, coeus_generate_docs, coeus_generate_commit, coeus_pixel_art_generate, coeus_pixel_art_find, and coeus_pixel_palette.

Example Workflows

Repository Intake

Use coeus_project_intake on the current repository with max_depth=3 and max_files=500.
Summarize the stack, key files, risks, and suggested workflows.

Model Routing

Use coeus_route for this task:
"Review a Python diff for correctness, backwards compatibility, and security."
Budget: standard. Speed: balanced. Requires vision: false.
Explain the selected provider, model, and workflow.

Code Review

Use coeus_review_bundle on the current git diff.
Focus on correctness, missing tests, security, and maintainability.
Lead with concrete findings ordered by severity.

Debugging

Use coeus_debug_playbook.
Symptom: The MCP client shows the server but tool calls fail.
Context: Include startup logs and the MCP client configuration.
Return ranked hypotheses and the smallest confirming experiments.

Multi-Provider Verification

Use coeus_multi_model_verify with this prompt:
"Does this implementation preserve provider neutrality? List blocking risks only."
Providers: auto. Temperature: 0.2.

Wildcard Ideation

Use coeus_wildcard for this problem:
How can we reduce CI build times without asking every team to rewrite their tests?

Set mode=chaotic. Return the three wildcard options and the strongman option.

Use mode=practical when the output needs near-term product or engineering ideas. Use mode=moonshot when the user explicitly wants speculative directions.

Release Readiness

Use coeus_release_readiness for a public GitHub release.
Include git status and docs drift.
Explain blockers and exact follow-up commands.

Configuration

Startup does not require every provider to be configured. Missing keys, missing CLI binaries, missing OAuth sessions, and missing dependencies are reported by coeus_healthcheck.

Development

Run the built-in unittest suite:

python3 -m unittest discover -v

Run pytest when dev dependencies are installed:

python -m pytest

The default suite is offline and never requires provider credentials. Bounded live release probes are opt-in and make one independent request per canonical provider:

COEUS_LIVE_PROVIDER_TESTS=1 ./.venv/bin/python -m pytest \
  tests/test_live_provider_smoke.py -q -rs

Each probe uses a tiny prompt and token budget, does not use fallback, and records the requested and actual model. Outcomes are reported separately: passed means the request returned a substantive response; failed means a configured provider returned another error; not_configured means its API credential or OAuth CLI is unavailable; and authentication_required means a configured provider rejected the authentication. The latter two outcomes are skips, never passes. Without COEUS_LIVE_PROVIDER_TESTS=1, all six provider probes skip before constructing the server or making a network/provider call.

Useful local smoke check:

python - <<'PY'
from mcp_server import CoeusMCPServer

server = CoeusMCPServer()
print(len(server.list_tools()))
print(server.call_tool("coeus_docs_drift_check", {"include_legacy": False}))
PY

Troubleshooting

Start with health and capability checks:

python - <<'PY'
from mcp_server import CoeusMCPServer

server = CoeusMCPServer()
print(server.call_tool("coeus_healthcheck", {"probe_network": False}))
print(server.call_tool("coeus_capabilities", {})["providers"])
PY

Common issues:

• mcp dependency is not importable: activate the virtualenv and run python -m pip install -e ".[dev]".

• No provider is ready: run the relevant OAuth login or configure one of the three direct Coeus API keys, then rerun coeus_healthcheck.

• A CLI is unavailable: install the CLI or set its COEUS_*_COMMAND path.

• A provider is configured but not ready: inspect catalog status and staleness in coeus_runtime_diagnostics.

• Tool calls work in a shell but not a desktop client: use an absolute command path and restart the client.

• coeus_multi_model_verify returns no attempts: no provider is configured and ready for the requested verification.

This release has a breaking provider-neutral tool surface. Existing configurations must migrate to coeus-ai and the coeus_* names; the exact old-to-new workflow map is in docs/migrations/vnext-provider-migration.md.