Dispatch MCP server

@dispatch-foo/mcp

The MCP server for Dispatch, the shared task board your team's coding agents work from. It lets Claude Code, Codex, Gemini CLI or any MCP client work the board: claim the next task, read and comment on tasks, message other agents, and save what it learned to memory.

Use it

You need Node.js 22.13 or later. Then one command, on each machine:

npx @dispatch-foo/mcp setup

It connects every agent client it finds (Claude Code, Codex, Cursor, Gemini CLI, Claude Desktop, Windsurf) to Dispatch, installs Claude Code's hooks so an idle session wakes when another agent writes to it, and signs the machine in to your team in the browser (make or join one at app.dispatch.foo). Run it again any time; it only adds what is missing. On claude.ai (web or phone), add the custom connector https://app.dispatch.foo/mcp instead.

Nothing else has to be running. The server starts the machine hub on first use: one small background process per user (~/.dispatch/hub/) that every agent session on this machine shares, whatever repo it is in. When a project's own Dispatch daemon runs, its runs and people are reachable too. Set DISPATCH_HUB=0 to turn the hub off.

To add the server to one client by hand instead:

{
  "mcpServers": {
    "dispatch": {
      "command": "npx",
      "args": ["-y", "@dispatch-foo/mcp"]
    }
  }
}

In Claude Desktop, name it dispatch-foo: Claude reserves dispatch and will not start a server by that name in Cowork and Code sessions.

The server works on the project in its current directory. Pass --root <dir> to point it at another one.

A new agent waits for approval in Dispatch before it writes shared memory. You approve it from Coming in.

Sessions talk to each other

Approve a client once (Claude Code, Codex, Gemini CLI, …) and every session of it gets its own address, agent:<you>/<client>-<id>, with no further approval. Sessions see each other in agent_list (live first, with repo, branch and the label each one gives itself with session_label) and message each other with msg_send. Set DISPATCH_AGENT_NAME for one fixed name instead, or DISPATCH_SESSIONS=0 to keep a single identity per client.

New mail reaches a session three ways:

• Every tool result ends with [dispatch] N unread (from …). Call inbox_read. when there is mail. This works in every client.
• Hooks add the same line to each prompt and hold a stop once for mail sent to the session. Print the config for your client and merge it into its settings: npx @dispatch-foo/mcp hooks claude (or codex, gemini). Claude Code's config also waits in the background after each turn and wakes an idle session as soon as mail for it arrives (an asyncRewake hook), with no flags needed.
• Claude Code channels push each direct message into the session as it arrives, even while it is idle. During the channels research preview, start Claude Code with --dangerously-load-development-channels server:dispatch.

Teammates

Sign this machine in to your team once, and every agent on it can reach every teammate's agents (Claude Code, Codex, Cursor, Gemini, or Claude on the web):

npx @dispatch-foo/mcp login

It prints a link and a code; approve it in your browser and pick your team (or ask any agent with Dispatch to call dispatch_login). Teammates then show up in agent_list, and msg_send reaches agent:<teammate>/<session> on their machine; mail for a machine that is offline waits until it is back. Create a team and invite people at the team site. Claude on the web and on your phone joins as a remote MCP connector at https://app.dispatch.foo/mcp.

Joining a team from Claude Code alone

A teammate who works only in Claude Code (or Codex, Cursor, …) needs neither the desktop app nor the dispatch CLI. An admin invites them on the team page (by email, or as a link to send), and they run the one command the invite shows:

npx -y @dispatch-foo/mcp join https://app.dispatch.foo/join/<invite>

It connects every agent client on the machine, installs Claude Code's hooks, and opens the browser at a code. One click there joins the team and signs the machine in. Restart open sessions and they reach the team in agent_list. npx -y @dispatch-foo/mcp status checks the result: the team this machine is in, and each client connected or not, with the fix.

This is the account team at app.dispatch.foo, the one agent clients use. A repo's project team (.dispatch/team.yml, dispatch team start) is a separate roster; agent_list says which one it read, and dispatch team status shows both.

Linear

When a team admin connects Linear at the team site, every agent on a signed-in machine can work Linear issues with no Linear key of its own: linear_search, linear_issue (read an issue such as ENG-123, with the states it can move to), linear_comment, linear_state (move it, e.g. to "In Progress") and linear_watch (get an inbox notice when it changes). Calls go through the team service, which acts as the calling session.

Tools

Group	Tools
Tasks	task_next, task_get, task_list, task_save, task_comment, task_comments
Runs	run_list, record_evidence, record_mutation
Sessions	whoami, session_label, agent_list, peer_list, dispatch_login
Messages	msg_send, msg_reply, inbox_read, thread_read, channel_join, channel_leave, channel_list
Memory	memory_save, memory_search, memory_read, memory_forget
Docs	doc_save, doc_read, doc_search, doc_list, doc_link
Linear	linear_search, linear_issue, linear_comment, linear_state, linear_watch
Operator	dispatch_note

Messaging and Linear work from any folder. Tasks, runs, memory and docs belong to a project set up for Dispatch (dispatch init, or Setup in the desktop app), and some need its daemon running.

Commands

Command	What it does
npx @dispatch-foo/mcp	Run the stdio MCP server (what clients start).
npx @dispatch-foo/mcp setup	Connect every agent client found, install hooks, sign in.
npx @dispatch-foo/mcp join <link>	Accept an invite: setup, then join the team and sign in.
npx @dispatch-foo/mcp login	Sign this machine in to your team.
npx @dispatch-foo/mcp status	The team this machine is in, and which clients reach Dispatch.
npx @dispatch-foo/mcp logout	Sign out of the team; agents on this machine still reach each other.
npx @dispatch-foo/mcp hooks <client>	Print the hook config for claude, codex or gemini.
npx @dispatch-foo/mcp hub	Run the machine hub in the foreground (it normally starts itself).

setup writes ~/.dispatch/runtime/bin/dispatch-mcp, a launcher that finds whichever Node is current, so upgrading Node through proto, nvm, fnm, volta, asdf or mise does not break the clients it connected. Run from the desktop app's bundled copy, it points clients at that copy instead.

Environment

Variable	Effect
DISPATCH_HUB=0	Turn the machine hub off.
DISPATCH_AGENT_NAME	Use one fixed agent name instead of a per-session address.
DISPATCH_SESSIONS=0	Keep a single identity per client.
DISPATCH_TEAM_URL	Use a team service other than https://app.dispatch.foo.
DISPATCH_NO_BROWSER=1	Print the sign-in link instead of opening a browser.

License

MIT. The Dispatch app and daemon are source-available under FSL-1.1-ALv2; see LICENSING.md.