MCP Troubleshooting

Use this page when an MCP client cannot connect to Itera, cannot discover tools, or returns a structured tool error. For normal setup, start with Connection setup. For tool inputs and safety notes, see the Tool reference and Agent guide.

Start with the supported connection

Production MCP uses OAuth through the remote MCP server:

https://api.iteradev.ai/mcp

Do not paste SOCIALGRAPH_ACCESS_TOKEN, bearer tokens, generic SocialGraph API tokens, custom Authorization headers, or token environment variables into normal production MCP configuration. If a client asks for a token instead of starting OAuth, switch to the client's remote MCP OAuth mode.

Failed discovery

Check these first:

• The server URL is exactly https://api.iteradev.ai/mcp.
• The client is configured for a remote or HTTP MCP server, not a local stdio command.
• The client supports OAuth protected resource discovery and authorization server discovery.
• Network policy, proxy settings, or browser privacy tools are not blocking https://api.iteradev.ai.

If discovery still fails, remove the saved MCP server entry in the client, add it again with only the server URL, and start a fresh OAuth login. Use the safe smoke test in Connection setup after discovery succeeds.

OAuth browser window does not open

OAuth normally opens a browser window or prints a URL for you to open manually.

Check these first:

• Run the client's login command or connect action again.
• Allow popups or external browser handoff for the MCP client.
• If the client prints an authorization URL, open that URL in the browser where you want to complete login.
• Confirm the client is using remote MCP OAuth mode rather than a manual-token mode.

If the browser still does not open, update the MCP client and retry. Do not work around the issue by adding a bearer token or custom authorization header.

Email code login fails

Email verification codes are short-lived and tied to the login flow that requested them.

Check these first:

• Use the newest code email and ignore older codes.
• Keep the same browser session open while entering the code.
• Confirm the email address belongs to the Itera account you want the MCP client to use.
• Restart the OAuth flow if the code is expired or was requested in a different browser session.

If repeated attempts fail, clear the saved client session for the Itera MCP server and start a fresh login.

TOTP or recovery code is required

Some accounts require multi-factor authentication after the email code.

Use a current authenticator-app code, or a recovery code if you cannot access the authenticator. If TOTP codes are rejected, check that the device clock is accurate and retry with a fresh code. If you cannot satisfy the MFA challenge, recover account access through your normal Itera account process before reconnecting the MCP client.

Scopes are denied

The production MCP server requires the MCP scope shown in Connection setup. If the consent screen is denied, incomplete, or attached to the wrong account, the client may connect but fail to list or run tools.

Recovery steps:

• Reconnect OAuth and approve the requested MCP scope.
• Confirm you are signing in with the intended Itera account.
• Clear the saved MCP client session if an earlier denied grant is being reused.
• Ask for access to the relevant Itera organization, project, task, or workflow instead of trying to bypass authorization locally.

Session expired

MCP clients usually refresh OAuth tokens automatically. If refresh fails, tool calls may start returning authentication errors or the client may stop listing tools.

Recovery steps:

• Run the client's reconnect or login flow for the Itera MCP server.
• If reconnect does not help, clear the saved client session for https://api.iteradev.ai/mcp and log in again.
• Restart the MCP client after reconnecting so it reloads the tool list.

Keep token storage inside the MCP client. Do not paste refreshed tokens into configuration files.

Tool is not shown in the client

If the Itera MCP server connects but a tool is missing:

• Restart or refresh the MCP client so it runs tool discovery again.
• Confirm the saved server URL is exactly https://api.iteradev.ai/mcp.
• Confirm OAuth completed for the account that has access to the target Itera data.
• Check whether the client hides tools when required scopes or account access are missing.
• Compare against the expected tools in the Tool reference.

If only mutating tools are missing, reconnect OAuth and confirm the requested scope was granted. Start with read-only tools after reconnecting.

Structured tool errors

Clients may show Itera MCP failures as tool errors, JSON error objects, or short status messages. Treat the status code as the durable signal and the exact message text as explanatory.

Safe structured errors use a high-level shape like:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A required input was missing or invalid."
  }
}

Error details should be safe to share with a user or support contact. They should not contain access tokens, authorization headers, cookies, stack traces, private environment variables, or unrelated internal state.

Common statuses and validation failures:

• NOT_FOUND: The requested project, task, planned PR, prototype, session, or other target was not found or is not visible to the signed-in account. Check exact IDs, then use search, task summary, timeline, plan, or prototype-list tools to find the right target.
• MCP invalid-params errors: The tool arguments fail MCP parameter validation, such as wrong types, invalid UUIDs, empty required strings, unsupported enum variants, or unsupported ticket providers. Compare the request with the required inputs in the Tool reference, then retry with corrected arguments.
• VALIDATION_ERROR: The request passed MCP parameter validation but failed business validation, such as an archived project or a ticket selection without its required provider.
• FORBIDDEN: The signed-in account is authenticated but not allowed to perform the requested action or access the requested target. Reconnect with the correct account, request access, or use a read-only tool that is allowed for the current account.

If an error follows a mutation attempt, stop and inspect current state before retrying. Repeating the same mutation can create duplicate tasks, follow-ups, answers, prototype actions, or recovery requests.

Mutating tool ran against the wrong target

Mutating tools can create tasks, claim planned PRs, answer questions, review specifications, send follow-ups, start prototypes, send prototype messages, control prototype sessions, or reconcile planned PR state.

If a mutation ran against the wrong project, task, planned PR, specification, prototype, or session:

1. Stop issuing mutating tools.
2. Read the task summary, timeline, plan, blockers, and prototypes for the affected task.
3. Confirm exactly what changed and whether a human needs to coordinate the recovery.
4. Use recovery tools only when the intended corrective action is clear.

For planned PR work, inspect the task plan and timeline before claiming or reconciling anything else. For prototype recovery, inspect prototypes and logs before stopping, retrying, rebasing, or checking out a commit. The Agent guide has prompt patterns that ask agents to state the exact target and expected state change before using mutating tools.

Prototype logs or runtime status is unavailable

Prototype log and runtime status tools can return no data when the task has no prototype, the selected prototype number is wrong, the prototype has no active or recent session, the session expired, or the signed-in account cannot access it.

Check these first:

• Use get_iteration_task_prototypes to list available prototypes and active session state.
• Retry get_iteration_task_prototype_logs with an explicit prototypeNumber.
• Inspect the task summary and timeline to confirm whether a prototype was started or selected.
• Use get_iteration_failure_review for the task or project when logs are missing but a prior failure may have been recorded.

If a prototype is inactive and you intend to change that state, confirm the task ID, prototype ID, and operation before using start, message, or control tools.