MCP server

instantprd-mcp is a stdio Model Context Protocol server that exposes one InstantPRD plan to an agent that speaks MCP. Same tokens, same API, same checkpoints as the CLI — the difference is that the agent calls tools instead of shelling out.

Use the CLI when your agent runs commands, and this when it does not. There is no reason to run both.

Register it

The server is published to npm and needs no installation of its own. With Claude Code:

claude mcp add instantprd -e INSTANTPRD_TOKEN=<your token> -- npx instantprd-mcp

Clients that take a JSON configuration file use the standard stdio form:

{
  "mcpServers": {
    "instantprd": {
      "command": "npx",
      "args": ["instantprd-mcp"],
      "env": {
        "INSTANTPRD_TOKEN": "iprd_…",
        "INSTANTPRD_PLAN": "<planId>"
      }
    }
  }
}

Create a token in Settings → Access tokens — account-scoped, or scoped to a single plan. The plan id is in the board URL: /workspace/<planId>/board.

Environment

Without a token the server refuses to start, prints the one-line fix and exits 1. A token that does not look like an access token is refused the same way, before any connection is opened.

Every tool also takes an optional plan argument that overrides INSTANTPRD_PLAN, so one server can work across several plans. With neither, a tool call comes back with an error telling the agent how to supply one.

Diagnostics go to stderr and only stderr: stdout carries the JSON-RPC stream, and one stray line on it corrupts the protocol. On a successful start, stderr says which app URL and which plan the server is bound to.

Tools

Six tools. Every one returns human-readable text and structuredContent — the same JSON the CLI receives — so an agent can read either.

get_plan_prd

Arguments: plan (optional).

The plan's PRD in Markdown, its feature structure per phase, and its progress. Read it before implementing: entity names, routes and flows come from the PRD, not from a task title. If the plan has no PRD yet, the tool says so rather than inventing one.

get_next_task

Arguments: plan (optional).

The next task with its full specification — description, acceptance criteria numbered from 0, test plan, layer, page, estimate, dependencies and status — plus the plan's progress and whether a checkpoint is blocking. Call it first, and again after every completed task.

When checkpoint.required is true the tool returns the checkpoint instead of a task to start, and says explicitly that a human must press Continue.

start_task

Arguments: ref (required, e.g. T-014), plan (optional), force (optional boolean).

Claims the task so the board shows it in progress. Rejected with 409 while a phase or layer checkpoint is open. force crosses that boundary deliberately — only pass it when the human asked for it.

complete_task

Arguments: ref (required), evidence (required), plan (optional).

Marks the task done and proves it. evidence is an object:

One checks entry per acceptance criterion of the task. Missing or failed criteria send the task to Needs review instead of Done; the response names which. Absent or malformed evidence answers 422 with the expected shape attached, which is what lets an agent correct itself in one turn.

fail_task

Arguments: ref (required), reason (required, 3–2 000 characters), plan (optional).

Marks the task failed with a concrete reason — what was tried, what blocks it. Use it instead of leaving a task in progress or claiming it is done. The reason is stored on the task and shown on the board.

report_checkpoint

Arguments: summary (required, 5–2 000 characters), plan (optional), ref (optional task ref).

Tells the board a phase or layer boundary was reached and records what was built, so the human can verify it. It appends to the task log and echoes the current checkpoint — it can never clear one. Clearing is the human pressing Continue on the board, and that action accepts a web session only. It is served by POST /api/cli/v1/checkpoints/:planId/report.

Errors

A failed call comes back as an MCP error result carrying the server's own message and details verbatim, plus a line telling the agent what to do next. The ones worth recognising:

Autonomous plans

On a plan with autonomous mode on, checkpoint.required is never true and checkpoint.autonomous is, so the loop runs end to end. The boundaries are still computed and every crossing is still recorded — the owner released the stop, they did not remove the audit trail.

The loop

get_next_task → start_task → implement exactly that task → run its test plan
              → complete_task with evidence → repeat

Stop at checkpoints. Never widen the scope of a task: the plan is ordered, and the next thing is always the next task.

Next

The same contract from a shell, with init, doctor and sync, is on Agent handoff. For reading plans and progress from your own tooling, see the Public API.