Agent Guide for Itera MCP

Use this guide when prompting a coding agent that can access the Itera MCP server.

Before you start

Configure the MCP server through OAuth first. The production server does not require users to paste bearer tokens, SOCIALGRAPH_ACCESS_TOKEN, custom Authorization headers, or token environment variables into normal MCP configuration. See Connection setup for the supported flow.

After the server is configured, many agents can infer that they should use Itera MCP when the task is clearly about Itera tasks, planned PRs, prototypes, specifications, or failure review. When you want deterministic behavior, say "use the Itera MCP" in the prompt.

You do not need to type raw tool names in normal prompts. Tool names are useful when precision matters, when the agent selected the wrong workflow, or when you need to distinguish a read-only preview from a mutating action. See the Tool reference for exact tool names and inputs.

Do not use real READY_UNCLAIMED planned PR IDs as smoke tests unless claiming execution is intended. For connection testing, use the safe not-found smoke test in Connection setup.

If discovery, OAuth, tool visibility, or structured tool errors fail, use Troubleshooting.

Read before write

For existing work, start with read-only context, then decide whether a state change is needed:

1. Search for or summarize the task first.
2. Inspect blockers, the current plan, timeline entries, prototypes, failure review, and prototype logs as needed.
3. Ask the agent to state the exact target ID, proposed action, and expected effect.
4. Only then use mutating tools.

This pattern is especially important for planned PR execution, prototype control, specification review, and recovery workflows. When creating a new task, confirm the target project and initial intent before calling the mutating tool.

Prompt templates

Task triage

• "Use the Itera MCP to summarize task <canonical task ID>, then show blockers and the current plan."
• "Use the Itera MCP to search recent tasks for project <project ID>, then summarize which ones need human input."

Creating a task

• "Use the Itera MCP to create a task in project <project ID> with this initial intent: <description>."

Use this only when starting new work is intended. Confirm the project ID and initial intent before calling the tool.

PR execution handoff

• "Use the Itera MCP to inspect planned PR <planned PR ID> for task <canonical task ID>, but do not claim it yet."
• "Use the Itera MCP to show the current plan for task <canonical task ID> and identify the next dependency-ready planned PR. Ask before claiming it."

Prototype debugging

• "Use the Itera MCP to show logs for prototype 1 of task <canonical task ID> and identify the likely startup issue."
• "Use the Itera MCP to list prototypes for task <canonical task ID>, then inspect the active prototype before suggesting any recovery action."

Answering task questions

• "Use the Itera MCP to show the open questions for task <canonical task ID>."
• "Use the Itera MCP to answer question <question ID> on task <canonical task ID> with: <answer>."

Reviewing specifications

• "Use the Itera MCP to show pending specifications for task <canonical task ID>."
• "Use the Itera MCP to approve specification <specification ID> for task <canonical task ID>."
• "Use the Itera MCP to reject specification <specification ID> for task <canonical task ID> with this feedback: <feedback>."

Submitting follow-ups

• "Use the Itera MCP to send this follow-up to task <canonical task ID>: <message>."
• "Use the Itera MCP to send this engineering follow-up to task <canonical task ID>: <message>."

If the phase is not obvious, ask the agent to confirm whether the follow-up is for PRODUCT, ENGINEERING, ENGINEERING_PLANNING, or PLANNING.

Failure investigation

• "Use the Itera MCP to show recent failures for project <project ID> and summarize the affected tasks."
• "Use the Itera MCP to show failure review entries for task <canonical task ID>, then compare them with the current plan."

Marking a planned PR merged

• "Use the Itera MCP to mark planned PR <planned PR ID> as merged after I confirm the GitHub PR has merged."

Use this only as a recovery action after the corresponding GitHub pull request has actually merged.

Confirm before changes

Ask the agent to pause for confirmation before using tools that change production state:

• Claiming a planned PR for execution. Confirm the canonical task ID, planned PR ID, and intent to implement that exact PR.
• Creating an iteration task. Confirm the project ID, project access, and exact initial intent.
• Starting or forking prototypes. Confirm the task ID, whether this is a new prototype or a fork, and any source checkpoint.
• Sending prototype messages. Confirm the prototype ID and exact message text.
• Controlling prototype sessions. Confirm the operation, target prototype or session ID, and commit SHA when checking out a commit.
• Answering questions or reviewing specifications. Confirm the question or specification ID, answer text, decision, and rejection feedback when applicable.
• Marking planned PRs merged. Confirm the planned PR ID and the external GitHub merge before reconciling Itera state.

If the agent cannot show the target ID and intended state change clearly, keep the workflow read-only until the missing context is resolved.