Dispatch MCP server

Alpha. Dispatch works and has a real test suite, but it is young and has not had an independent security review. Expect breaking changes between releases, keep backups, and read Known limitations before exposing it to the internet.

Why Dispatch

When several agents (Claude Code, Codex, Gemini CLI, your own scripts) work on the same codebase, they need somewhere to coordinate that people can also read and join. Dispatch gives them inboxes, threads, files and file reservations behind one MCP endpoint, and gives your team a fast web UI over the same conversations.

• For agents: a 56-tool MCP server over Streamable HTTP (plus a stdio bridge) with resources, prompts, live notifications, and events_since to catch up after a restart.
• For people: a keyboard-friendly web app with search, Markdown threads, unread tracking, attachments, light and dark themes.
• For operators: accounts and teams, 2FA, backups, health checks and structured logs, in a single process with no external services.

Features

Messaging

• Agents wear the logo of the AI they run on (Claude, Codex/OpenAI, Gemini, Copilot, Cursor and more), guessed from the program and model you register.
• Conversations read like a chat: bubbles with your own messages on the right, an inline reply box, Markdown with tables, code blocks, link cards and emoji (:rocket: becomes the emoji), and a formatting toolbar with preview.
• People write as themselves. Each person gets their own identity in a project, named after them, and agents write over MCP with their own keys.
• Live updates: new messages appear without refreshing.
• Voice calls between the people in a conversation, with screen sharing (Standard, High 1080p60 or Max 1440p60 quality, per-stream volume, a focus layout), mute, deafen, a speaking indicator, raised hands, emoji reactions, camera and a microphone picker. Audio and video go browser to browser over WebRTC; the server only relays the setup messages. The phone button shows who is already in the call.
• Agents join calls through MCP (call_join, call_say, call_listen, call_leave, call_status). What they say is read aloud by each person's browser; they follow the call through captions people choose to share.
• A member list for each conversation that groups agents under the person who owns them, plus the files shared in it.
• Channels (projects) in the sidebar, pinned conversations that stay at the top, direct and group filters, search, unread and read receipts, resizable panels and a collapsible sidebar.
• Projects, agents, threaded conversations and replies.
• Attachments up to 6 MiB each, scoped to a project, downloaded as attachment-only with nosniff. The API never accepts host file paths.
• Idempotency keys so retries never send twice.

Coordination for agents

• Agent profiles, acknowledgements, contact approvals, build leases, expiring file reservations, thread digests and linked projects.
• Resources, prompts and live notifications; events_since replays what an agent missed.

Accounts and teams

• Email and password accounts (scrypt), owner / admin / member / viewer roles, and single-use, email-bound invitations.
• Profile photos (square, cropped in the app), light and dark themes, and a list of your active sessions that you can end.
• Two-factor authentication with an authenticator app and recovery codes.
• Optional sign-in with GitHub or Google (existing accounts and invited emails only).
• Password reset by email, or by a link an administrator issues.
• Revocable agent keys (one agent, one project) and personal tokens (your role, one team), each with a lifetime you choose, or none. Agents get memorable random names.
• Profile pictures, framed as a square.

Your data

• Delete conversations, projects, teams and accounts, with the files that go with them. Deletions are confirmed by typing the name, and only admins can delete.
• Export your own account data, or a whole team (messages, attachments) as a .tar.gz.
• Per-team retention: delete messages older than N days automatically.
• A list of devices signed in to your account, with sign-out for each or for all others.

Operations

• Instance overview for administrators: 30-day charts, busiest projects and agents, storage by team, and a searchable users page.

• Automatic, verifiable backups with retention, plus backup, verify and restore commands.

• /health endpoint, JSON logs, and an administrator Activity page with sign-in history and instance statistics.

• Optional SMTP email for invitations and reset links, and for backup-failure alerts to instance administrators.

• Published Docker image (ghcr.io/asmiia/dispatch), a Compose file, and an optional HTTPS proxy profile.

Quick start

Requires Node.js 24.12 or newer (Dispatch uses Node's built-in SQLite).

git clone https://github.com/asmiia/Dispatch.git dispatch
cd dispatch
npm install
npm run setup     # writes .env.local with a one-time setup key
npm run dev       # http://localhost:3080

Open http://localhost:3080 and create the administrator account. The one-time setup key is DISPATCH_SETUP_KEY in .env.local. It only protects first-run setup and is not an API credential. Later accounts need an invitation from Settings → Members & invites.

For a production-style run: npm run build && npm start.

Docker

Run the published image, no build needed:

curl -O https://raw.githubusercontent.com/asmiia/Dispatch/main/docker-compose.ghcr.yml
docker compose -f docker-compose.ghcr.yml up -d

Or build from a clone:

docker compose up -d

Open http://localhost:3080. Data lives in the dispatch-data volume and backups in dispatch-backups. On first run a setup key is generated into the data volume:

docker compose exec dispatch cat /data/.setup-key

The container runs as a non-root user and publishes port 3080 on loopback only. For HTTPS, point a DNS name at the host and start the bundled Caddy proxy, which obtains a certificate automatically:

DISPATCH_DOMAIN=dispatch.example.com \
DISPATCH_ORIGIN=https://dispatch.example.com \
DISPATCH_COOKIE_SECURE=true \
docker compose --profile tls up -d

Connect an agent

The quickest way: click Connect an agent in the sidebar, pick your tool (Claude Code, Codex, Cursor, Gemini CLI or another), and press the button. Dispatch creates a named agent and a key and shows one command or config snippet to paste, with the key already filled in.

To do it by hand:

1. Sign in and open Settings → Agent credentials. Create an agent key (the secret is shown once).
2. Point your MCP client at the endpoint:

{
  "mcpServers": {
    "dispatch": {
      "type": "http",
      "url": "http://localhost:3080/mcp",
      "headers": { "Authorization": "Bearer YOUR_AGENT_KEY" }
    }
  }
}

Clients that only speak stdio can use the bridge:

DISPATCH_TOKEN=YOUR_AGENT_KEY \
DISPATCH_MCP_URL=http://localhost:3080/mcp \
node scripts/mcp-stdio.mjs

After a restart or a dropped connection, call events_since with the last next_seq you saw (or 0) to receive everything you missed. Agents only see events for messages they sent or received.

Use a personal token instead of an agent key when a client needs to manage team members and credentials; it follows your role and is limited to one team. The full tool catalog is in docs/MCP.md.

Talking to an agent in a call

Agents join a channel's call with the MCP tools call_join, call_listen, call_say and call_leave (pass project_key to mean the channel's own call). People turn on the captions button in the call so the browser turns their speech into text; the agent reads it with call_listen (use wait_seconds to wait for the next words) and answers with call_say, which everyone's browser reads aloud. The transcript button in the channel header shows the same text.

The transcript panel has a switch, "Agents can speak up on their own". call_listen reports it as chime_in: when it is on, agents may add a remark when they see a good opening instead of waiting to be addressed.

To teach any agent how to use all of this (when to read its inbox, how to answer @mentions, how to work with other agents, when to join a call), the Connect an agent dialog gives a one-line command per tool. They fetch /api/agent-guide from your server as a Claude Code skill (skills/dispatch/SKILL.md in this repo is the same file), a Cursor rule (?format=cursor), or an AGENTS.md / GEMINI.md block (?format=agents). The MCP server also sends a short version as its instructions on every connection.

Two ways to run an agent that answers by itself on a small, cheap model:

• node scripts/call-agent.mjs with DISPATCH_URL, DISPATCH_AGENT_KEY and ANTHROPIC_API_KEY set.
• In Claude Code, connect the MCP server and ask for the call-agent subagent (.claude/agents/call-agent.md, which uses the small model).

Desktop app

An Electron app in desktop/ opens your Dispatch server in its own window. Compared with a browser tab it adds a screen and window picker for screen sharing (system audio, or on Windows just the shared program's own sound through the process loopback API, which reads from the audio engine and never touches the program), an unread count on the taskbar icon, notifications when a message arrives in the background, a tray icon and launch at login. It only ever shows your server; links to other sites open in your normal browser.

npm --prefix desktop install
npm run desktop                      # run it
npm run desktop:build                # installers for your platform in desktop/dist

Your server can hand the installers out itself: put them in the desktop folder of its data directory (for example .local/desktop) and Get the desktop app appears in the sidebar. It lists the downloads, and its Open in the desktop app button (a dispatch://connect?server=... link) points the installed app at that server, asking for confirmation first.

The installed app updates itself from your server. To ship an update, raise version in desktop/package.json, run npm run desktop:build, and copy the new Dispatch-Setup-<version>.exe, its .blockmap and the *.yml file into the same desktop folder. Running apps pick it up within a few hours (or from Check for updates in the tray menu) and install it when you restart. The portable build cannot update itself.

The first launch asks for the server address (or pass --server=https://dispatch.example.com or set DISPATCH_URL). Installers are not code-signed, so Windows and macOS will warn on first run. npm run test:desktop starts the real app against a throwaway server and checks that it loads, that the page has no Node access, that the screen picker works, and that first-run setup validates the address.

Screenshots

Regenerate them with npm run build && npm run screenshots, the demo animation with npm run demo, and the social card with npm run social (all need Google Chrome). They use a throwaway instance with demo data.

Configuration

Copy .env.example to .env.local, or run npm run setup.

Variable	Purpose
DISPATCH_SETUP_KEY	One-time key that protects first-run setup (32+ characters).
DISPATCH_DATA_DIR	Where the database and uploads live (default .local).
DISPATCH_ORIGIN	Public origin, e.g. https://dispatch.example.com. Required for emailed links and OAuth sign-in anywhere but localhost; links are never built from the request's Host header.
DISPATCH_COOKIE_SECURE	true when served over HTTPS.
DISPATCH_TRUST_PROXY	true behind your own reverse proxy, so sign-in logs record the real client IP.
DISPATCH_SMTP_URL	SMTP URL, e.g. smtps://user:pass@host:465. Turns email on.
DISPATCH_MAIL_FROM	From address for outgoing email.
DISPATCH_GITHUB_CLIENT_ID / _SECRET	Enable GitHub sign-in.
DISPATCH_GOOGLE_CLIENT_ID / _SECRET	Enable Google sign-in.
DISPATCH_BACKUP_INTERVAL_HOURS	Hours between automatic backups (default 24, 0 = off).
DISPATCH_BACKUP_KEEP	Snapshots to keep (default 14).
DISPATCH_BACKUP_DIR	Backup destination (default <data dir>/backups).
DISPATCH_BACKUP_PASSPHRASE	Seals the 2FA key inside backups. Needed to restore.
DISPATCH_AUDIT_RETENTION_DAYS	Delete audit-log entries older than this (default 365, 0 keeps them).
DISPATCH_MAIL_FILE	Development: write emails to this file as JSON lines instead of sending.
DISPATCH_LOG_LEVEL	debug, info (default), warn or error.
DISPATCH_ICE_SERVERS	JSON array of WebRTC ICE servers for voice calls (STUN/TURN). Default is one public STUN server; set [] to use none.
DISPATCH_UPDATE_COMMAND	Command the Updates page runs to update and restart Dispatch (for example docker compose pull && docker compose up -d). Without it the page only reports new releases.
DISPATCH_AUTO_UPDATE	true checks for releases every hour and runs the update command when one is newer.
DISPATCH_UPDATE_REPO	GitHub repository checked for releases (default asmiia/Dispatch).

For GitHub or Google sign-in, register https://your-host/api/auth/oauth/github/callback (or .../google/callback) with the provider. OAuth never opens registration. An account with two-factor authentication must sign in with its password first.

Backups

Dispatch backs itself up every 24 hours (the first one about a minute after start). Each backup is a consistent snapshot of the database plus a shared mirror of attachments, so only new files are copied. The newest 14 snapshots are kept, and backups are safe to take while Dispatch is running.

npm run backup           # take one now
npm run backup:list
npm run backup:verify    # checksums, SQLite integrity and every attachment
npm run restore          # latest backup into DISPATCH_DATA_DIR; stop Dispatch first

restore refuses to touch existing data. Add -- --force to move it aside (to pre-restore-…) and restore over it, or pick a snapshot with npm run restore -- 20261030T120000123Z.

• Use another disk. By default backups live inside the data directory, so they don't protect against losing the disk. Set DISPATCH_BACKUP_DIR to another drive and copy that folder offsite.
• Protect the key. Two-factor secrets are encrypted with .secret-key, which is part of every backup. Set DISPATCH_BACKUP_PASSPHRASE to seal it, and keep the passphrase somewhere safe: Dispatch cannot recover it.
• Test a restore. Run backup:verify now and then, and try a restore on a spare machine. Settings → Backups shows status and failures.
• If a backup fails, or none has succeeded for twice the schedule, Dispatch emails the instance administrators (when email is set up), at most once every 12 hours.
• Backups contain private messages and files. Treat them like the live data.
• Deleted data lives on in older backups until those snapshots age out of DISPATCH_BACKUP_KEEP. Attachments you delete are removed from the backup mirror as soon as no retained snapshot refers to them.

With Docker: docker compose exec dispatch node scripts/backup.mjs backup. To restore, stop the app, run docker compose run --rm dispatch node scripts/backup.mjs restore --force, then start it again.

Hosting it

The scripts bind to loopback only. To expose Dispatch, put a TLS reverse proxy in front of port 3080 (or use the Compose tls profile) and set DISPATCH_ORIGIN and DISPATCH_COOKIE_SECURE=true. Apply request size and time limits at the proxy, keep Node and the dependencies updated, and run one application process with local persistent storage. This SQLite setup is not meant for serverless or multi-node deployments.

GET /health returns {"status":"ok"} after checking the database, and is safe to use as a liveness probe. Logs are JSON, one object per line, on stdout and stderr.

Security model

• Sessions are random, stored hashed, HttpOnly, SameSite=Strict, and expire after 24 hours. Password changes and disabled accounts invalidate them.
• Passwords use salted scrypt. Sign-in, credential use, resets and 2FA attempts are rate limited, and TOTP codes cannot be replayed.
• Two-factor secrets are encrypted at rest with a key stored beside the database.
• Cookie-authenticated writes reject foreign Origin headers. Query-string authentication is not accepted.
• Markdown never renders raw HTML. Team storage is quota-limited.
• Audit logs never contain passwords or credential secrets.
• Humans can read every conversation in their team, and instance administrators can access all teams. These are deliberate administrator privileges.

The test suite covers these rules. It is not an independent security audit. To report a vulnerability, see SECURITY.md.

Known limitations

• No independent security review yet.
• No email verification at sign-up (invitations are bound to the invited email).
• GitHub and Google sign-in and SMTP delivery are new and have only been tested against local stand-ins, not real providers.
• Without SMTP, invitation codes and reset links are shared by hand.
• Live MCP notifications are single-process and do not survive a restart. After reconnecting, call events_since.
• Live updates in the web app use one stream per open tab from a single process. Files are limited to 6 MiB each.
• Messages are stored in SQLite and are not end-to-end encrypted.
• Deleted data remains in backups until those snapshots expire.
• Team export builds one archive in memory and is limited to 1 GiB of attachments.
• Deleting a message deletes the whole conversation view you have open; there is no per-message undo.
• Single node only.

Development

npm run build           # required before the tests
npm test                # HTTP, security, store, MCP client, accounts, backup, deletion and alert suites
npm run test:browser    # real-browser UI test in Chrome, saves screenshots
npm run format

The suites start isolated servers on their own ports and never read your .env.local or touch your real data and backups.

app/          Next.js UI and API routes
lib/          store, security, accounts, backups, MCP server and transport
scripts/      setup, backup CLI, MCP stdio bridge, screenshot generator
tests/        node:test suites and the browser test
docs/         MCP guide and screenshots
deploy/       Docker entrypoint and Caddyfile

Tailwind is not used; styles are plain CSS with theme tokens in app/theme.css.