Connect to Itera MCP

Use this guide to connect any compatible remote MCP client to the production Itera MCP server. Client-specific examples below include MCP Inspector and Codex CLI, but the production server is not tied to one client.

Production endpoint

Use the remote MCP resource URL:

https://api.iteradev.ai/mcp

Production MCP access is authenticated through OAuth. Your MCP client should discover the protected resource metadata, discover the authorization server, open the login flow with PKCE, exchange the authorization code for tokens, and refresh tokens when needed.

The production discovery URLs are:

• Protected resource metadata: https://api.iteradev.ai/.well-known/oauth-protected-resource/mcp
• Authorization server metadata: https://api.iteradev.ai/.well-known/oauth-authorization-server
• Required MCP scope: itera.planned_pr.execute

Client setup

Most compatible clients use the same connection shape:

• Choose the client's remote or HTTP MCP server mode.
• Enter only the Itera MCP server URL.
• Let the client start OAuth discovery and browser login.

Client labels vary, but the setup should stay URL-only. Do not add token fields for normal production setup. Users should not be asked to paste SOCIALGRAPH_ACCESS_TOKEN, bearer tokens, generic SocialGraph API tokens, custom Authorization headers, or token environment variables into MCP client configuration.

If a production client asks for a token value instead of starting the OAuth flow, switch to the client's remote MCP OAuth connection mode.

Codex CLI example

Codex CLI is one concrete URL-only configuration example. Other MCP clients do not need this TOML file.

[mcp_servers.itera]
enabled = true
url = "https://api.iteradev.ai/mcp"

For Codex CLI, this config registers the server but does not complete OAuth by itself. After adding the config, run the login command once for the configured server name:

codex mcp login itera

The command starts the MCP OAuth flow and stores the resulting credentials in Codex.

Login flow

After the client starts OAuth, expect the Itera login flow to ask for:

1. Email address
2. Email verification code
3. TOTP or a recovery code if multi-factor authentication is required for the account

When login completes, the client stores and refreshes the OAuth tokens itself. Keep token storage inside the MCP client.

MCP Inspector

In MCP Inspector, choose a remote or HTTP MCP server connection and enter:

https://api.iteradev.ai/mcp

Start the connection from Inspector so it can perform the OAuth discovery and browser login flow. Do not configure a manual bearer token for production.

Safe smoke test

Use a deliberately nonexistent canonical task ID with a syntactically valid planned PR UUID. This verifies that authentication, tool routing, and error handling work without claiming a production planned PR.

{
  "tool": "claim_planned_pr_for_execution",
  "arguments": {
    "canonicalTaskId": "00000000-0000-4000-8000-000000000000",
    "plannedPullRequestId": "00000000-0000-4000-8000-000000000001"
  }
}

The expected result is a high-level not-found error, for example:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "No matching iteration task or planned PR was found."
  }
}

Different clients may render the error as a tool failure instead of raw JSON. The important signal is NOT_FOUND, not the exact message text.

Do not test with real READY_UNCLAIMED planned PR IDs unless claiming production execution is intended.

Human prompts

These prompts are useful once the connection succeeds:

• "Use the Itera MCP to search for my recent iteration tasks."
• "Use the Itera MCP to get the summary for iteration task <canonical task ID>."
• "Use the Itera MCP to run the safe not-found smoke test for a nonexistent planned PR."

For the full list of tools and example prompts, see the Tool reference. For agent prompting workflows, see the Agent guide. If connection, OAuth, discovery, or tool visibility fails, see Troubleshooting.