ai-coord-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ai-coord-mcp create a task to refactor the authentication module"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ai-coord-mcp
A shared coordination layer between multiple AI coding assistants — not an orchestrator.
This MCP server never launches, manages, or talks to any AI process. It only exposes a task queue, a per-task message thread, and progress reporting, all persisted as human-readable JSON on disk. Claude Code and OpenCode (or any other MCP-capable client) are launched manually, in separate terminals, and both point their MCP config at this server. Claude typically plays coordinator (creates/reviews tasks); OpenCode plays implementer (claims/updates/completes them) — but the server has no opinion about that, it just stores state.
Claude Code (Sonnet) OpenCode (DeepSeek/Qwen/etc.)
│ │
│ create_task, list_tasks, │ claim_task, update_progress,
│ approve_task, request_revision │ complete_task, post_message
▼ ▼
ai-coord-mcp (this server)
│
▼
.ai/coordination/*.json (on disk)Design
Transport: stdio. Each client spawns its own copy of this server as a subprocess. "The same server" means the same storage directory (
COORDINATION_DIR), not one process. Every tool call re-reads the relevant JSON file from disk before mutating it; writes go through temp-file-then-rename (writeJsonAtomic) so a reader never sees a half-written file; a cross-process mutex (withLock,src/storage/lock.ts) built onmkdirguards concurrent writers, with stale-lock reclaim after 10s and an ownership token per holder.IDs: sequential
task-0001,task-0002, … assigned under a short-lived lock. Validated against/^task-\d{4,}$/before being joined into any filesystem path.Optimistic concurrency: every task carries a
versioncounter. Passexpected_versionto any mutating tool to get aConflictErrorinstead of a silent overwrite.Not implemented: binary attachments (the
filesfield is path references only, not stored content), archiving (thearchive/directory exists but nothing writes to it), typedbranch/commitfields (use themetadataconvention below instead), structured Definition-of-Done /verify_command(useexpected_outputinstead), task relationships /parent_id/blocks(usetagsto group instead), MCP Resources /resources/subscribe(usewait_for_taskinstead).
Status model:
pending --claim_task--> claimed --update_progress--> in_progress
^ | |
| | both claimed and in_progress can complete_task--> completed
| | |
| └──────────────────────cancel_task─────────────────┐ approve_task│request_revision
| | | |
└───────────────reopen_task (from cancelled/completed/approved)◄────────────┘ ▼ ▼
approved revision_requested
(loops back through
update_progress →
in_progress again)update_progress auto-advances claimed or revision_requested to in_progress on its
first call in that cycle — there's no separate "start_task" tool.
Related MCP server: chatgpt-claude-bridge
Storage layout
.ai/coordination/
tasks/task-0001.json one file per task (includes its own audit history[])
messages/task-0001.json array of {id, taskId, author, timestamp, content}
progress/task-0001.json latest snapshot + full history of updates
archive/ reserved, unused
.locks/ transient lock directories, safe to delete if emptyEverything is plain JSON — cat .ai/coordination/tasks/task-0001.json works fine while
the server is running.
Setup
cd ai-coord-mcp
pnpm install
pnpm run buildBoth Claude Code and OpenCode need to point at the same COORDINATION_DIR (an absolute
path) so they share state regardless of which directory each was launched from.
Claude Code — add to .mcp.json (project) or via claude mcp add:
{
"mcpServers": {
"ai-coord": {
"command": "node",
"args": ["/absolute/path/to/ai-coord-mcp/dist/index.js"],
"env": {
"COORDINATION_DIR": "/absolute/path/to/shared/.ai/coordination"
}
}
}
}OpenCode — add the equivalent entry to its MCP config (opencode.json /
~/.config/opencode/config.json, depending on your OpenCode version):
{
"mcp": {
"ai-coord": {
"type": "local",
"command": ["node", "/absolute/path/to/ai-coord-mcp/dist/index.js"],
"environment": {
"COORDINATION_DIR": "/absolute/path/to/shared/.ai/coordination"
}
}
}
}If COORDINATION_DIR is unset, the server defaults to <cwd>/.ai/coordination — only
safe if you know both clients will be launched from the same working directory.
Getting started
Build the server and wire up
COORDINATION_DIRfor both clients (Setup above).Launch Claude Code and OpenCode in separate terminals, both in the shared repo.
In Claude Code, create a task:
Create a task: title "Sort inventory list", description "Implement stable sort by SKU for the inventory panel, keep the existing filter hooks working", expected_output "inventory.ts updated, existing tests still pass, new test for empty list". → calls
create_task, returnstask-0001(statuspending).In OpenCode:
Check ai-coord for any pending tasks. → calls
claim_next_task, works the task, callsupdate_progressa few times, thencomplete_task.Back in Claude Code:
Review task-0001 and approve or request revision. → reviews the diff, calls
approve_taskorrequest_revision(the latter posts feedback to the thread; OpenCode reads it viaget_messagesand repeats fromupdate_progress).
Tools
Tool | Purpose |
| Create a task (status |
| List task summaries (no |
| Fetch one task by id, full record including |
| Substring search over title/description/tags, same summary shape as |
|
|
| Atomically claim the first eligible pending task (optionally by |
| Block (polling, lock-free) until a task's status changes or |
|
|
|
|
|
|
| any open status → |
|
|
| Append to a task's conversation thread |
| Read a task's thread, optionally only messages |
| Report |
| Latest progress snapshot + history |
All mutating tools accept an optional expected_version — pass the task's current
version to get a ConflictError instead of clobbering a concurrent change.
Every status-changing tool above (claim_task through reopen_task) returns the same
summary shape as list_tasks — no history[] — so an implementer with a small context
window (a local model, say) isn't handed the whole growing transition/note log back on
every call. Same for update_progress: it returns the current snapshot, not the growing
history[]. get_task/get_progress remain the only tools that return full history.
Workflow conventions
Waiting for work: use
wait_for_taskover pollingget_task/list_tasks— one call instead of N, blocks server-side without holding a lock, returnstimed_out: trueas a normal result.Picking up work: use
claim_next_taskoverlist_tasks({status:"pending"})+claim_task— same two steps, atomic, retries automatically if another claimer wins the race.Git state: no typed
branch/commitfield. Convention:create_task'smetadatacarries{ baseCommit, branch }; both agents read/write those same keys.expected_outputplus this README is the Definition-of-Done contract.Implementer loop:
claim_next_task(orclaim_taskon a specific id) → work → a fewupdate_progresscalls →complete_task. If revision is requested,get_messagesfor the feedback, then repeat fromupdate_progress.Coordinator loop:
create_task→wait_for_task(or check back later) → oncompleted, review the diff atworking_directory→approve_taskorrequest_revision.
Tests
pnpm testRuns node:test (via tsx) over every src/**/*.test.ts file: the storage layer
(atomic writes, cross-process lock semantics including the stale-lock/ownership-token
edge case, id generation, message/progress persistence) and the full tool surface
(state-machine transitions, TASK_ID schema rejecting malformed/traversal ids, version
conflicts) driven through the real registerXxx() functions against a fresh temp
COORDINATION_DIR per test file.
Available Tools
16 toolsapprove_taskA
Approve a completed task (typically called by the creator/reviewer after checking the implementer's work). Returns the task summary (no history[] — call get_task for that).
Inputs: by (required), id (required), note, expected_version.
cancel_taskA
Cancel a task that is not already completed/approved/cancelled. Returns the task summary (no history[] — call get_task for that).
Inputs: by (required), id (required), reason, expected_version.
claim_next_taskA
Atomically claim the first eligible pending task (optionally filtered by tag) instead of a separate list_tasks + claim_task round trip. Skips tasks pre-assigned to someone else. Returns null if no eligible pending task is available, otherwise a task summary (no history[] — call get_task for that).
Inputs: assignee (required), tag.
claim_taskA
Claim a pending task as the implementer working on it. Fails if the task was pre-assigned to someone else. Returns the task summary (no history[] — call get_task for that).
Inputs: id (required), assignee (required), expected_version.
complete_taskA
Mark a claimed/in-progress/revision-requested task as completed and ready for the creator to review. Returns the task summary (no history[] — call get_task for that).
Inputs: by (required), id (required), note, expected_version.
create_taskA
Create a new coordination task for an implementer (e.g. OpenCode) to pick up. Starts in status 'pending'.
Inputs: title (required), creator (required), description (required), tags, +6 more.
get_messagesA
Fetch a task's conversation thread, optionally only messages after a given ISO timestamp.
Inputs: taskId (required), since.
get_progressA
Fetch the latest progress snapshot (and history) for a task. Returns null if no progress reported yet.
Inputs: taskId (required).
get_taskA
Fetch full details for a single task by id, including its status, version, and history.
Inputs: id (required).
list_tasksA
List coordination tasks, optionally filtered by status, assignee, creator, or tag. Returns a lightweight summary per task (no history[], plus a computed idleSeconds while claimed/in_progress) so repeated polling stays cheap — call get_task for the full record including history.
Inputs: tag, status, creator, assignee.
post_messageA
Post a message to a task's conversation thread (e.g. clarifications, review feedback, status notes).
Inputs: author (required), taskId (required), content (required).
reopen_taskA
Reopen a cancelled/completed/approved task back to pending, clearing its assignee and prior progress so it can be re-claimed. Returns the task summary (no history[] — call get_task for that).
Inputs: by (required), id (required), reason, expected_version.
request_revisionA
Send a completed task back to the implementer for changes. Posts the feedback as a message on the task's thread. Returns the task summary (no history[] — call get_task for that).
Inputs: by (required), id (required), feedback (required), expected_version.
search_tasksA
Full-text search over task titles, descriptions, and tags (case-insensitive substring match). Returns the same lightweight summary shape as list_tasks (no history[]) — call get_task for the full record.
Inputs: query (required).
update_progressA
Report progress (0-100, whole numbers) on a claimed/in-progress/revision-requested task. The first call in a claim or revision cycle automatically advances the task's status to 'in_progress'. Rejects tasks not currently open for work (pending, completed, approved, cancelled). Returns the current snapshot (no history[] — call get_progress for that).
Inputs: by (required), taskId (required), percent (required), notes, +2 more.
wait_for_taskA
Block (polling, lock-free) until a task's status changes, or until timeout_seconds elapses — use instead of repeatedly calling get_task in a loop. Without until_status, returns as soon as status differs from its value at call time; with until_status, waits specifically for that status. Timing out is a normal result (timed_out: true), not an error — re-call to keep waiting.
Inputs: id (required), until_status, timeout_seconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Each tool targets a distinct resource/action: task CRUD, claiming, lifecycle transitions (complete/cancel/reopen/approve/revision), messaging, progress, and waiting. Even similar tools like list_tasks/search_tasks and claim_task/claim_next_task are clearly differentiated by purpose and described behavior.
All tools follow a consistent verb_noun pattern in snake_case (create_task, get_task, claim_task, update_progress, wait_for_task). Verb choices are semantically aligned with actions (list/get/search for reads; claim/complete/cancel for state changes), making the set predictable and easy to navigate.
At 16 tools, the set sits at the upper boundary of typical scope, but every tool serves a distinct purpose in the coordination workflow. The slightly elevated count is justified by the inclusion of specialized tools like claim_next_task and wait_for_task that optimize common operations.
The surface covers the full task lifecycle (create, read, claim, complete, cancel, reopen, approve, revision) plus messaging and progress tracking. Minor gaps exist: there's no tool to edit task metadata (e.g., title, description, assignee) after creation, but this can be worked around via cancel/recreate.
Maintenance
Related MCP Connectors
Shared task layer for AI agents: tasks, handoffs and decisions that persist across tools.
Shared control plane for AI coding agents — tasks, memory, decisions, file locks. 12 tools.
Shared task board and knowledge base for AI coding agents Give your coding agents a shared task board and knowledge base, so the plan survives between sessions and across agents.
One shared project for a team's coding agents: decisions, a task board and handoffs.
Related MCP Servers
- AlicenseBqualityAmaintenanceA coordination layer for coding agents that provides memorable identities, inbox/outbox messaging, searchable message history, and file lease management to prevent conflicts. Uses Git for human-auditable artifacts and SQLite for fast queries, enabling multiple agents to collaborate across projects without stepping on each other.412,240MIT
- FlicenseNot gradedqualityCmaintenanceEnables two coding assistants to coordinate task creation, claiming, messages, and completion through a shared local workflow queue while using GitHub issues, branches, commits, and PRs as the source of truth.-
- AlicenseNot gradedqualityCmaintenanceEnables multiple AI coding agents to coordinate on a shared software project by registering, claiming tasks, declaring file intents, publishing structured change reports, and handing off context, with a local dashboard showing state in near real time.MIT
- AlicenseAqualityBmaintenanceEnables multiple AI coding-agent sessions on one machine to hand tasks to each other and get results back through a shared local folder of JSON messages, with no cloud, database, or network service. Supports direct messages, broadcasts, blocking receive, and an optional headless worker that picks up, runs, and auto-replies to tasks.6MIT