@dougbots/avenor-mcp

Note: Since v0.x, avenor mcp is the canonical Go-native MCP server built into the avenor binary itself — no Node/Bun required. See docs/mcp.md for the primary MCP setup and tool reference. This Node.js package is an alternative for OpenCode-based setups or when you prefer npm-based tooling.

MCP server that makes avenor agent runs available as tools inside any MCP-compatible client (Claude Code, Claude Desktop, Cursor, etc.).

When you need this

You have avenor installed and you want Claude (or another MCP host) to spawn and manage agent runs — kicking off a Codex or Gemini session, checking its status, answering permission prompts, tailing event logs, and resuming completed runs.

This package is the MCP layer. It depends on @dougbots/avenor-core for all the actual wiring (supervisor lifecycle, binary discovery, socket protocol). You don't need to know the internals to use it.

Prerequisites

• Node 20+ (or Bun — the server runs on Bun but is shipped as ESM)
• avenor binary on your PATH, or set AVENOR_BIN=/path/to/avenor

If the binary isn't found at startup, the MCP server will fail to connect.

Install

npm install @dougbots/avenor-mcp

Or run it on-demand with npx (see configuration below).

Configuration

stdio transport (default)

Add to your MCP host config. For Claude Code, edit ~/.claude/mcp.json:

{
  "mcpServers": {
    "avenor": {
      "command": "npx",
      "args": ["@dougbots/avenor-mcp"],
      "env": {
        "AVENOR_BIN": "/opt/homebrew/bin/avenor"
      }
    }
  }
}

For Claude Desktop, use ~/.config/Claude/claude_desktop_config.json with the same shape.

Skip AVENOR_BIN if avenor is already on your PATH. On a fresh session, the supervisor auto-starts the avenor daemon the first time you call a tool.

SSE transport

When you need the MCP server running as a long-lived HTTP service (multiple clients, remote access via tunneling, etc.), use SSE mode. Set MCP_TRANSPORT=sse and provide an auth token:

MCP_TRANSPORT=sse \
MCP_AUTH_TOKEN="my-secret" \
MCP_PORT=3748 \
npx @dougbots/avenor-mcp

Then in your MCP host config:

{
  "mcpServers": {
    "avenor": {
      "url": "http://127.0.0.1:3748/mcp",
      "headers": {
        "Authorization": "Bearer my-secret"
      }
    }
  }
}

SSE mode restricts incoming requests to localhost / 127.0.0.1 / [::1] origins. The auth token is required — the server returns 401 without it.

Tools

This surface registers tool names without the avenor_ prefix — spawn, status, result, answer_permission, message, peers, events, kill, shutdown, and workflow. MCP clients namespace their own servers (Claude Code shows them as mcp__avenor__spawn, for example), so the prefix would only repeat itself. The avenor binary's own MCP server uses the same names.

spawn

Start a new agent run.

Returns { run_id, label, supervisor_id }. The run_id is what you pass to the other tools.

Direct and roster modes

Use both roster_file and roster_entry for roster mode. Every entry inside the roster file must declare backend and at least one of agent or model. A call in roster mode cannot also pass direct agent, model, or backend fields, because the entry supplies all three; the refusal names the field to drop. Direct mode permits all three identity fields to be omitted independently, including a backend-only request; omitted values use runtime defaults.

{
  "dir": "/repo",
  "prompt": "Analyze the repository",
  "roster_file": "/repo/roster.json",
  "roster_entry": "planner"
}

The roster map is strict: system and unknown entry fields are rejected. An entry's thinking is a default, so a run-level thinking still wins. Whichever value applies is validated against the effective backend chosen by direct mode or by the roster entry. A resumed session cannot switch to a different backend.

status

Get the status of one run, or list all runs. Use the compact lifecycle view for progress and pending permission checks; full remains the compatibility default.

Returns a status object (or array) with status being one of running, waiting, done, failed, timeout, killed, or unknown (no status reported, or one that is not recognized). done, failed, timeout and killed are terminal; unknown is not. When a run is blocked on a permission request, the response includes a pending_permission field with the available options.

result

Wait for a run to finish and return its complete final output without transcript or event details.

Terminal responses include ready: true and output when the backend exposed one. A pending permission returns immediately. If the result wait itself expires, the response has ready: false and timed_out: true without changing the run.

answer_permission

Respond to a permission prompt that paused a run.

Returns { ok: true } on success. Throws if no permission request is pending for the given run.

message

Send a message to another run, withdraw a pending ask, resume a completed run, or deliver a control reply. Cross-variant argument rules are enforced by the shared router, so an argument outside the chosen action's field set is an error rather than a silent no-op.

target is a run id, a peer label, or "self". timeout_ms must be an integer no greater than the shared ask cap. This tool does not take supervisor_id; it is bound to the default supervisor. A router tool error is returned as an MCP error result carrying the contract sentence and a code.

Every successful result is the shared contract object in snake_case (action, outcome, text, and message_id, run_id, label, reply, sentinel_file, on_event when the outcome carries them), returned as the structured content, with the contract sentence as the text content, exactly like the Go MCP host.

peers

List the visible agent sessions, rename a run, or read a run's last agent message.

last is read-only. This surface never publishes a turn of its own, so last of the server's own session returns the shared empty result. This tool does not take supervisor_id; it is bound to the default supervisor. The structured result is {peers}, {renamed} or {last} in snake_case, the same object the Go MCP host returns.

events

Fetch the event log for a run. Useful for inspecting what an agent did.

Returns an array of event objects ({ type, ts, ... }) in chronological order.

kill

Terminate a run without shutting down the supervisor. Other runs and the supervisor itself keep running.

shutdown

Stop the avenor supervisor and clean up sentinel files.

Returns { ok: true, cleaned_up: [...] }. Use this when you're done with avenor in your session or when the supervisor crashes and needs to be restarted.

workflow

Drive a durable workflow instance. One action selects the verb; every action takes an optional supervisor_id for multi-supervisor setups. Read-only actions need no permission; gate, complete and cancel keep their authority checks.

The underlying control methods are in docs/control-protocol.md.

Typical workflow

1. Spawn a run: spawn(agent: "codex", dir: "/path/to/project", prompt: "audit the API routes for auth gaps")
2. Check lifecycle when needed: status(run_id: "<id>", view: "lifecycle") for progress or pending permissions.
3. If permission requested: run answer_permission with the offered option.
4. Retrieve the result: result(run_id: "<id>") waits and returns the complete final output.
5. Inspect history when needed: events(run_id: "<id>") returns raw recent events.
6. Iterate: message(action: "resume", target: "<id>", message: "now write tests for that")
7. Clean up: shutdown() when you're finished.

Package structure

@dougbots/avenor-mcp
├── @dougbots/avenor-core  (workspace dep — supervisor, tool implementations)
├── @modelcontextprotocol/sdk  (MCP server + transports)
└── hono  (HTTP framework for SSE transport)

The server is a single file (src/mcp.ts), compiled to dist/index.js by tsdown. The avenor-mcp bin entry runs it directly.