# Amicus MCP server

> Enables Claude to orchestrate multi-model LLM councils for structured peer review and parallel sidecar chats with other models.

- Repository: https://github.com/BourbonDog/amicus
- Page: https://hostedmcp.org/servers/bourbondog/amicus
- Transport: stdio
- Stars: 2
- License: MIT
- Latest version: 4.16.1

## Install

### Claude Code

```sh
claude mcp add --env 'OPENROUTER_API_KEY=<YOUR_OPENROUTER_API_KEY>' amicus -- npx -y amicus
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "amicus": {
      "command": "npx",
      "args": [
        "-y",
        "amicus"
      ],
      "env": {
        "OPENROUTER_API_KEY": "<YOUR_OPENROUTER_API_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "amicus": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "amicus"
      ],
      "env": {
        "OPENROUTER_API_KEY": "<YOUR_OPENROUTER_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"amicus","type":"stdio","command":"npx","args":["-y","amicus"],"env":{"OPENROUTER_API_KEY":"<YOUR_OPENROUTER_API_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "amicus": {
      "command": "npx",
      "args": [
        "-y",
        "amicus"
      ],
      "env": {
        "OPENROUTER_API_KEY": "<YOUR_OPENROUTER_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add amicus --env 'OPENROUTER_API_KEY=<YOUR_OPENROUTER_API_KEY>' -- npx -y amicus
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.amicus]
command = "npx"
args = ["-y", "amicus"]

[mcp_servers.amicus.env]
OPENROUTER_API_KEY = "<YOUR_OPENROUTER_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'OPENROUTER_API_KEY=<YOUR_OPENROUTER_API_KEY>' amicus npx -- -y amicus
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "amicus": {
      "command": "npx",
      "args": [
        "-y",
        "amicus"
      ],
      "env": {
        "OPENROUTER_API_KEY": "<YOUR_OPENROUTER_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `OPENROUTER_API_KEY` | no | yes | OpenRouter API key (recommended multi-model route). Optional when a provider key is configured via 'amicus setup' (~/.config/amicus/.env) or OpenCode auth.json. |
| `AMICUS_SKIP_POSTINSTALL` | no | no | Set to 1 when a plugin/client manages registration itself (skips npm postinstall side effects). |
| `LOG_LEVEL` | no | no |  |

## Tools (16)

- `amicus_start`: Spawn an Amicus session with a different LLM. Returns a task ID immediately. Mode selection: use INTERACTIVE (default, noUi: false) for research, exploration, analysis, and any task where the user benefits from watching progress live. It eliminates the polling problem entirely. Use HEADLESS (noUi: true) only for background automation the user does NOT need to monitor. When in doubt, use interactive. EXCEPTION: When spawning multiple sessions simultaneously, ALWAYS use HEADLESS (noUi: true) for all of them unless the user explicitly requests interactive. Opening multiple Electron windows at once is disruptive. For headless mode, prefer calling amicus_wait with the task ID — one blocking call replaces the sleep+status loop; re-call it while it returns timedOut: true. Fallback (no amicus_wait tool available): ALWAYS run `sleep 25` in your shell before each amicus_status call to enforce the polling interval. For interactive mode, do not poll. Wait for the user to tell you they've clicked Fold, then use amicus_read. Call amicus_guide first if you need help choosing a model or writing a good briefing. Pass includeContext: false when the briefing is fully self-contained.
- `amicus_status`: Check the status of a running Amicus session. Returns status (running/complete), elapsed time, and progress info. Primarily for headless mode — in interactive mode, wait for the user to tell you the session is done instead of polling.
- `amicus_wait`: Wait (block inside one tool call) until an Amicus session or fan-out wave reaches a terminal state, or until timeoutMs elapses. Returns the same JSON shape as amicus_status plus {timedOut, waitedMs} (and {hint} on timeout), with next_poll stripped/replaced. PREFER this over sleep+amicus_status polling for headless runs: one call replaces many polls. If it returns timedOut: true the run is still going — simply call amicus_wait again. Works for any session or wave, including ones started by other processes.
- `amicus_read`: Read the results of a completed Amicus session. Returns the summary by default, or full conversation history, or session metadata. Every mode is capped at ~50KB by default; when content exceeds the cap and no offset/limit/tail is given, the response is the TAIL of the content with a "[truncated: ...]" notice as the first line — use offset/limit or tail to page through the rest. (read-only)
- `amicus_list`: List all Amicus sessions for the current project. Shows task ID, model, status, tag, createdAt, and briefing excerpt. Use `search` to filter by id/tag/briefing substring. (read-only)
- `amicus_resume`: Reopen a previous Amicus session with full conversation history preserved. The session continues in the same OpenCode session. Returns a task ID immediately — use amicus_wait to block until done (or poll amicus_status).
- `amicus_continue`: Start a new Amicus session that inherits a previous session's conversation as context. The previous session's messages become read-only background for the new task. Returns a task ID immediately — use amicus_wait to block until done (or poll amicus_status).
- `amicus_setup`: Open the Amicus setup wizard to configure API keys and default model. Launches an interactive Electron window for configuration.
- `amicus_abort`: Abort a running Amicus session. Stops the OpenCode agent immediately. Use when a session is taking too long or is no longer needed.
- `amicus_fanout`: Run N models on the SAME prompt in parallel (one shared engine) and aggregate the results. Headless only. Returns {waveId, taskIds[]} immediately. Preferred: call amicus_wait with the waveId — one blocking call replaces polling; re-call it while it returns timedOut: true. Fallback (no amicus_wait tool available): poll amicus_status with the waveId (run `sleep 25` between polls). Either way, amicus_read the waveId when done for the aggregated JSON wave document (per-leg summaries inside). Each leg is also an ordinary session readable by taskId.
- `amicus_council_tally`: Deterministic council tally over an ASSEMBLED, de-anonymized input (meta + findings + adjudications + rankings). Peers-only tier cascade (Confirmed/Contested/Disputed/Singleton) + street-cred. Pure + synchronous: returns the tally record immediately. No subprocess, no polling. Claude assembles the input and may override margin tiers afterward. (read-only)
- `amicus_council_stats`: Per-model reviewer reliability derived from the append-only council ledger (avg peers-only street-cred, lifetime confirm/fact-error rates). Read-only; no inputs required. (read-only)
- `amicus_verdict`: Merge a tally record with Claude's Stage-4 decisions into the verdict object (final tiers after overrides, decisions, applied flags). Pure + synchronous; returns the verdict. Writes nothing unless render:true AND outDir are given — then it also refreshes <outDir>/report.html.
- `amicus_council_run`: Run the FULL headless council engine: Stage-1 independent reviews → anonymized peer cross-review → deterministic tally → non-bench chair synthesis → verdict.json + report.html, without any orchestrating agent. Returns {runId, runDir} immediately (async). Preferred: call amicus_wait with the runId; re-call while it returns timedOut: true. Artifacts land in runDir. Exit semantics: run.json status complete (full run), partial (degraded: dead leg / thin judging / no chair verdict), error, aborted.
- `amicus_spend`: Read-only cross-run cost rollup from the spend ledger (mirrors the CLI `amicus spend` query flags). Filter by since/wave/council/project/model/op, keep only failed (wasted) rows, and group by a dimension. Returns a versioned spend doc (ids/numbers/paths only, never model-generated text) — never fenced. (read-only)
- `amicus_guide`: Get detailed usage instructions for Amicus — when to spawn sessions, how to write good briefings, agent selection guidelines, and the async workflow pattern. Call this first if you haven't used Amicus before. (read-only)

## FAQ

### How do I trigger a council review in Claude Code?

You can trigger it by saying 'council review this' to Claude or by running /amicus:council directly on the plugin channel.

### Can I run the council using local models for free?

Yes, you can point the council at local OpenAI-compatible servers like Ollama, LM Studio, or vLLM to run it at $0 cost.

### Does the council work in CI environments without Claude?

Yes, you can run the council headless in CI using the CLI command without needing a Claude runtime.

### What models are supported for sidecar chats?

You can fork conversations to Gemini, GPT, DeepSeek, or any other model.
