MCP Tool Reference

Use these tools through a compatible MCP client after connecting to the Itera MCP server. Tool names are listed for precision, but normal users can ask in natural language and let the client select the right tool.

Safety

Start with read-only context tools before using mutating tools. Read the task summary, timeline, plan, blockers, prototypes, or failure review first, then confirm the exact task, planned PR, specification, prototype, or session ID before changing state.

Mutating tools can create new iteration tasks, claim implementation work, answer questions, review specifications, create follow-ups, start prototypes, send prototype instructions, or recover prototype sessions. Use them only when the intended state change is clear.

For practical prompt templates and confirmation patterns, see the Agent guide. For connection issues, missing tools, and structured error statuses, see Troubleshooting.

Task creation

Use this tool only when you intentionally want to start new work in Itera from an MCP client.

create_iteration_task

• Classification: mutating.
• Purpose: Create and queue a new iteration task. This starts new work: it creates the task, records the initial product intent, snapshots project repositories, and queues the first product-phase run.
• Required authorization: Authenticated MCP viewer with the itera.planned_pr.execute capability/scope, access to the target project, and project membership.
• Required inputs: projectId and initialIntent.
• Optional inputs and defaults: ticketProvider and ticketSelectionId. ticketProvider currently supports JIRA and is required when ticketSelectionId is supplied.
• Output summary: SUCCESS with the new canonical task ID, task summary, and created initial task run. The initial run is created in the PRODUCT phase with status QUEUED.
• Structured statuses: SUCCESS, NOT_FOUND when the project is not found, and VALIDATION_ERROR for business validation failures such as an archived project or a ticket selection without a provider.
• Invalid parameters: Invalid UUIDs, empty initialIntent, unsupported variants, and unsupported ticket providers fail as MCP invalid-params errors.
• Example prompt:
  • "Create an Itera task in project <project ID> with this initial intent: <description>."
• Safety note: Confirm the project ID, project access, and initial intent before calling this tool.

Discovery and task context

Use these tools to find tasks and build context before deciding what action to take.

search_iteration_tasks

• Classification: read-only.
• Purpose: Search iteration tasks by organization, project, owner, participant, phase, status, and updated time.
• Required inputs: organizationId.
• Optional inputs and defaults: projectId, ownerId, participantId, phases, statuses, updatedTimeFrom, updatedTimeTo, orderBy, orderDirection, page, and pageSize. Results default to updated descending order. pageSize defaults to 20 and can be at most 100. BLOCKED status is accepted as an alias for NEEDS_INPUT.
• Output summary: A bounded page of matching iteration tasks with enough identifying and status context to choose the next read-only tool.
• Example prompts:
  • "Find blocked iteration tasks in organization <organization ID>."
  • "Search recent tasks for project <project ID>."

get_iteration_task_summary

• Classification: read-only.
• Purpose: Get the current high-level state for one iteration task.
• Required inputs: canonicalTaskId.
• Optional inputs and defaults: None.
• Output summary: Current task status, blockers, latest run, current plan summary, and associated prototype summaries when available.
• Example prompt:
  • "Show me a summary of iteration task <canonical task ID>."

get_iteration_task_timeline

• Classification: read-only.
• Purpose: Read a bounded chronological history for an iteration task.
• Required inputs: canonicalTaskId.
• Optional inputs and defaults: maxItems defaults to 100 and can be at most 500.
• Output summary: Timeline entries such as messages, follow-ups, questions, assignee changes, phase or status changes, prototype completions, and planned PR milestones.
• Example prompt:
  • "Show the timeline for iteration task <canonical task ID>."

Questions, blockers, and specifications

Use these tools when a task is blocked, needs human input, or has a specification awaiting review.

get_iteration_task_blockers

• Classification: read-only.
• Purpose: Explain why an iteration task is blocked or waiting for input.
• Required inputs: canonicalTaskId.
• Optional inputs and defaults: None.
• Output summary: Current human blockers, open questions, pending or rejected specification reviews, relevant task run detail, and suggested human next action.
• Example prompt:
  • "Why is iteration task <canonical task ID> blocked?"

answer_iteration_task_questions

• Classification: mutating.
• Purpose: Answer one or more explicit open questions on an iteration task.
• Required inputs: canonicalTaskId and at least one { questionId, answer } entry.
• Optional inputs and defaults: taskRunId when the answer should be attached to a specific run.
• Output summary: Confirmation that the supplied question answers were recorded.
• Example prompt:
  • "Answer question <question ID> on iteration task <canonical task ID> with: <answer>."
• Safety note: Answer only questions you intend to resolve. Use get_iteration_task_blockers first if you need the current open question IDs.

submit_iteration_task_follow_up

• Classification: mutating.
• Purpose: Send a follow-up instruction or clarification to an existing iteration task.
• Required inputs: canonicalTaskId, follow-up text, and phase. Supported phases are PRODUCT, ENGINEERING, ENGINEERING_PLANNING, and PLANNING.
• Optional inputs and defaults: None.
• Output summary: Confirmation that the follow-up was recorded for the task phase.
• Example prompts:
  • "Send this follow-up to iteration task <canonical task ID>: <message>."
  • "Send this engineering follow-up to iteration task <canonical task ID>: <message>."
• Safety note: Follow-ups may change how the task proceeds. Include the intended phase or be ready for the client to ask which phase to use.

review_iteration_task_specification

• Classification: mutating.
• Purpose: Approve or reject one explicit specification for an iteration task.
• Required inputs: canonicalTaskId, specificationId, and decision. decision must be APPROVE or REJECT. Rejections require feedback.
• Optional inputs and defaults: None.
• Output summary: Confirmation that the specification review decision was recorded.
• Example prompts:
  • "Approve specification <specification ID> for task <canonical task ID>."
  • "Reject specification <specification ID> for task <canonical task ID> because <reason>."
• Safety note: Specification review changes task readiness. Review the task blockers or summary first when you are not sure which specification is pending.

Planned PR execution

Use these tools to inspect and claim scoped implementation work.

get_iteration_task_plan

• Classification: read-only.
• Purpose: Read the current implementation plan for an iteration task.
• Required inputs: canonicalTaskId.
• Optional inputs and defaults: None.
• Output summary: Planned PRs, dependencies, specifications, execution state, and the next dependency-ready planned PR.
• Example prompt:
  • "Show the current implementation plan for iteration task <canonical task ID>."

approve_iteration_task_plan

• Classification: mutating.
• Purpose: Approve the current implementation plan for an Itera iteration task by canonical task ID. The task must already have a current plan pending review in the planning flow. A successful first approval moves the task to building/ready state and sends the same project task, timeline, and list update notifications as the normal app approval path.
• Required authorization: Authenticated MCP viewer with the itera.planned_pr.execute capability/scope and write access to the iteration task.
• Required inputs: canonicalTaskId.
• Optional inputs and defaults: None.
• Output summary: SUCCESS with idempotent, the task summary, and the approved current plan summary. idempotent: false means this call approved the plan. idempotent: true means the plan was already approved.
• Structured statuses: SUCCESS, NOT_FOUND when the task is not found, and VALIDATION_ERROR for business validation failures such as no current plan, task not in the planning phase, or a current plan that has not reached review. A retry for the already-approved current plan returns SUCCESS with idempotent: true, not VALIDATION_ERROR.
• Invalid parameters: Missing or empty canonicalTaskId fails as an MCP invalid-params error.
• Example prompt:
  • "Approve the current plan for iteration task <canonical task ID>."
• Safety note: Use get_iteration_task_summary, get_iteration_task_blockers, or get_iteration_task_plan first unless you already know the exact task and intend to approve its current plan. This is a state-changing approval that can unblock implementation work.

get_planned_pr_context

• Classification: read-only.
• Purpose: Preview implementation context for one planned PR without claiming it.
• Required inputs: canonicalTaskId and plannedPullRequestId.
• Optional inputs and defaults: None.
• Output summary: The scoped implementation context needed to decide whether to claim that exact planned PR.
• Example prompt:
  • "Show implementation context for planned PR <planned PR ID> of task <canonical task ID>."

claim_planned_pr_for_execution

• Classification: mutating.
• Purpose: Claim one exact planned PR for implementation.
• Required inputs: canonicalTaskId and plannedPullRequestId.
• Optional inputs and defaults: None.
• Output summary: Confirmation that the planned PR was claimed for execution.
• Example prompt:
  • "Claim planned PR <planned PR ID> for iteration task <canonical task ID>."
• Safety note: Claim only a planned PR you intend to implement. Use get_iteration_task_plan or get_planned_pr_context first to confirm the planned PR is the right unit of work.

mark_planned_pr_merged

• Classification: mutating recovery.
• Purpose: Reconcile one explicit planned PR as merged.
• Required inputs: plannedPullRequestId.
• Optional inputs and defaults: None.
• Output summary: Confirmation that the planned PR was marked merged.
• Example prompt:
  • "Mark planned PR <planned PR ID> as merged."
• Safety note: Use this only as an intentional reconciliation action after confirming the planned PR really merged.

Prototype debugging and control

Use these tools to inspect, start, message, and recover prototypes associated with an iteration task.

get_iteration_task_prototypes

• Classification: read-only.
• Purpose: List bounded prototype summaries for an iteration task.
• Required inputs: canonicalTaskId.
• Optional inputs and defaults: None.
• Output summary: Prototype selection state, activity state, checkpoints, active session status, and authorized runtime URLs when available.
• Example prompt:
  • "List the prototypes for iteration task <canonical task ID>."

get_iteration_task_prototype_logs

• Classification: read-only.
• Purpose: Read startup and dev runtime logs for a prototype associated with an iteration task.
• Required inputs: canonicalTaskId.
• Optional inputs and defaults: prototypeNumber defaults to 1. maxEntries can be between 1 and 2000.
• Output summary: Recent startup and dev runtime log entries for the selected prototype.
• Example prompts:
  • "Show logs for prototype 2 of iteration task <canonical task ID>."
  • "Show logs for the prototype of iteration task <canonical task ID>."

start_iteration_task_prototype

• Classification: mutating.
• Purpose: Start a prototype for an iteration task, or fork a prototype from an existing checkpoint.
• Required inputs: canonicalTaskId.
• Optional inputs and defaults: creationMode. To fork, use creationMode set to FORK with both sourcePrototypeId and sourceCheckpointId.
• Output summary: The started prototype details.
• Example prompt:
  • "Start a prototype for iteration task <canonical task ID>."
• Safety note: Starting or forking a prototype creates new prototype activity. Confirm the task ID and whether a fork is intended before starting.

send_prototype_message

• Classification: mutating.
• Purpose: Send an instruction to an existing prototype.
• Required inputs: prototypeId and message text.
• Optional inputs and defaults: None.
• Output summary: Confirmation that the prototype message was queued.
• Example prompt:
  • "Tell prototype <prototype ID> to fix the broken navbar."
• Safety note: Prototype messages queue agent work. Use the prototype list or logs first if you need to confirm the target prototype.

control_prototype_session

• Classification: mutating recovery.
• Purpose: Stop, cancel, retry, rebase, or check out a commit for prototype recovery.
• Required inputs: operation plus the identifier required by that operation. STOP_SESSION requires prototypeSessionId. CANCEL_RUN, RETRY_LAST_REQUEST, and REBASE_FROM_MAIN require prototypeId. CHECKOUT_COMMIT requires prototypeId and commitSha.
• Optional inputs and defaults: None.
• Output summary: Confirmation that the prototype control operation was requested.
• Example prompts:
  • "Stop prototype session <prototype session ID>."
  • "Retry the last request for prototype <prototype ID>."
  • "Rebase prototype <prototype ID> from main."
• Safety note: Recovery operations affect active prototype state. Inspect prototypes and logs first unless you already know the exact session or prototype to recover.

Failure review

Use this tool to inspect prior implementation failures before repeating work.

get_iteration_failure_review

• Classification: read-only.
• Purpose: Read bounded failure review entries for a project or one iteration task.
• Required inputs: canonicalTaskId or projectId.
• Optional inputs and defaults: page and pageSize. pageSize defaults to 20.
• Output summary: Failure review entries with task or prototype context and log references when available.
• Example prompts:
  • "Show recent failures for project <project ID>."
  • "Show failure review entries for task <canonical task ID>."