intentdocs / docsMenu ▾

MCP Integration

Example workflows

Concrete agent-loop examples using the MCP tools and resources — picking up a story, proving acceptance criteria, and handling a blocker.

These walk through what an agent actually calls, in order, for common situations. Tool names are written for the local server (intent mcp); swap in the remote server's equivalents from Tools & resources if you're on the HTTP endpoint (mark_in_progress → start_story, mark_done → complete_story, etc.).

Picking up the next story

  1. Call list_stories (or read the intentdocs://project/status resource first, to decide whether to keep going or stop for the session).
  2. Pick the highest-priority todo story whose dependencies are done — the same selection logic as intent next on the CLI.
  3. Call mark_in_progress with the story's ID.
  4. Read intentdocs://project/storymap (or get_context, on the standard/all mode) for full context — personas, related stories, data model references — beyond what list_stories alone returns.
  5. Implement.

Proving acceptance criteria before marking done

Acceptance criteria have a method — executable, agent_self_check, visual_render, or founder_confirm. Only executable criteria have something an agent can literally run and observe.

  1. After implementing, run each executable criterion's command yourself (or defer to intent check if you're shelling out to the CLI from within the agent session).
  2. Call report_criteria with the story ID and one result per criterion: { criterion_id, status: "pass" | "fail" | "blocked", detail }. detail should describe what you actually observed — it's the evidence trail, not a formality.
  3. Call mark_done. If a must criterion isn't reported as pass, the tool call returns the blocking list instead of completing — fix it and re-report, or pass force: true if you have a real reason to override (this gets recorded).

Raising a blocker instead of forcing past it

If a must criterion keeps failing after a few real attempts, don't loop indefinitely and don't force it through:

  1. Call raise_blocker with story_id, summary, attempting, failing, and decision_needed — a single, concrete decision the founder needs to make (not "help me debug this").
  2. Stop working the story. Don't call mark_done afterward — raise_blocker is the terminal action for that story until a human responds.

Reacting to a cancelled story

If a human runs intent stop <id> on a story an agent is mid-flight on, the local MCP server refuses further tool calls on it (except list_stories/get_status) and returns a message starting with "🛑 Development of ... was cancelled." An agent's loop should treat that response as a hard stop for the current story, not a transient error to retry.

Logging a decision an agent made unprompted

If an agent makes a real architectural call mid-implementation — a library choice, a schema tradeoff — call log_decision with a short title, the reasoning, and a category (architecture, product, technical, or trade-off). This is what shows up in CLAUDE.md after the next intent sync --context, so the next session (agent or human) doesn't re-litigate it.