MCP server for Claude Code, Claude Desktop and Codex
itervox mcp (v0.2.8, #216) is a local Model Context Protocol
server. It runs on your machine, talks to the running Itervox daemon of the
project over its API, and gives an MCP client — Claude Code, Claude Desktop,
Codex or any other — tools to read the board and memory and, if you allow it,
to run the fleet. Ask your editor’s agent “what is blocked?”,
“dispatch ENG-12” or “what do we know about the staging DB?”.
It speaks MCP over stdio only. A remote (HTTP) MCP endpoint is not part of
itervox mcp.
Before you start
Section titled “Before you start”- A daemon is running for the project (
itervoxin the project directory;itervox statuslists it). itervoxis on thePATHthe MCP client uses. Claude Desktop does not read your shell profile: give it the absolute path (which itervox).
Set it up
Section titled “Set it up”Claude Code
Section titled “Claude Code”In the project directory:
claude mcp add itervox -- itervox mcpClaude Code starts the server in the project directory, so it finds that
project’s daemon. To share the setup with your team, add it to the
project’s .mcp.json instead:
claude mcp add --scope project itervox -- itervox mcpThe Itervox Claude Code plugin bundles this server (viewer scope by default) together with skills for setup, doctor, CI and day-to-day operation.
To let the agent dispatch, pause, reply and steer (see Scopes):
claude mcp add itervox -- itervox mcp --token-scope operatorClaude Desktop
Section titled “Claude Desktop”Edit claude_desktop_config.json (Settings → Developer → Edit Config;
on macOS ~/Library/Application Support/Claude/claude_desktop_config.json)
and restart Claude Desktop. Desktop does not start servers in your project,
so name it with --project:
{ "mcpServers": { "itervox": { "command": "/usr/local/bin/itervox", "args": ["mcp", "--project", "/Users/you/code/my-repo"] } }}Add one entry per project (itervox-api, itervox-web, …) to use several.
Add the server to ~/.codex/config.toml:
[mcp_servers.itervox]command = "itervox"args = ["mcp", "--project", "/Users/you/code/my-repo"]For operator tools add "--token-scope", "operator" to args.
Results are compact JSON. Secrets are redacted, and agent output (the transcript, tool output, the last message of a run) is never returned — only what the dashboard summarises.
Read tools (viewer)
Section titled “Read tools (viewer)”| Tool | What it returns |
|---|---|
board_summary | Running agents (turns, tokens, start), retries, paused issues, issues waiting for input, capacity, the dispatch pause, the number of recent failures and blocked issues, and the feed cursor. |
list_issues | Issues the daemon sees, filtered by tracker state, Itervox orchestratorState (idle, running, retrying, paused, input_required, pending_input_resume), label or query text; limit (default 50). |
get_issue | One issue (description cut to 4 KB) with its run context: current step, last tool call, turns and tokens, the pending question or guardrail approval, changed files and handoffs (Now & Changes). |
explain_blockers | Tracker blockers from the dependency audit, inferred dependencies (confidence, whether they gate dispatch, stale, overridden), cycles and stale blockers; for one issue with identifier. |
recent_failures | The daemon’s recent classified failures, newest first. |
feed_since | Events after a cursor from the event feed; pass the returned nextSeq as since next time. |
recall | Memory for a query, ranked exactly like run-time retrieval: pinned entries first, then by relevance, active entries in the profile’s scope, within a token budget (default the run-time memory budget). See Memory. |
Write tools (operator)
Section titled “Write tools (operator)”Each keeps the dashboard’s rules.
| Tool | What it does |
|---|---|
dispatch | Moves the issue to the first active state, like Dispatch on the board. While all dispatch is paused it refuses and changes nothing; it never resumes dispatch by itself. |
pause_dispatch / resume_dispatch | Pause all dispatch (optional reason and minutes) and resume it. Running agents continue. |
reply_input | Answers an agent waiting for input. Guardrail approvals are refused: they stay human-only on the dashboard (Guardrails). The reply is sent as an agent reply, so the daemon also refuses it if an approval appears meanwhile. |
steer | Sends a steering message to the issue’s running agent (Sessions). An agent waiting for input takes reply_input instead. |
remember | Proposes a memory (text, optional type, scope, tags, issue). It is created as proposed and waits in Memory → Lessons until a human approves it; it never reaches a run before that. |
Scopes
Section titled “Scopes”itervox mcp uses a scoped token:
- By default it creates, on first use, a stored viewer token named
mcpand remembers its secret in.itervox/mcp-token.json(mode 0600, gitignored). Viewer clients see the read tools only — the write tools are not even listed. --token-scope operatorcreates an operator token instead (replacing and revoking the viewer one) and lists the write tools.--token TOKENorITERVOX_TOKENuses a token you created withitervox token create, with that token’s scope.
itervox token list shows the mcp token; itervox token revoke ID cuts
the MCP server off at once, and its next start creates a new token. The
secret is never printed or logged; stdout carries MCP messages only and
diagnostics go to stderr.
A daemon running with server.allow_unauthenticated: true takes no token;
--token-scope still decides which tools are offered.
Troubleshooting
Section titled “Troubleshooting”- “no running itervox daemon for …”: start
itervoxin that project, or pass--project(or--url http://127.0.0.1:8090). - “the daemon refused the token (401)”: the
mcptoken was revoked or rotated; restart the MCP server (in Claude Code:/mcp→ reconnect). - A write tool says it needs an operator token: re-add the server with
--token-scope operator.
See also the CLI reference.