# MCP server

Give ChatGPT, Codex, Claude Code, Cursor, VS Code, and other MCP clients governed access to Product Context and feedback.

iterateTo serves standards-based streamable HTTP at `https://iterateto.com/api/mcp`. Agents can retrieve a bounded Product Context bundle, search it, inspect individual records, and—when granted the right scope—create, update, or archive records. Feedback tools remain available on the same connection.

## Connect

For a local agent or IDE, create an `itr_` personal access token under [Dashboard → Settings → API keys](/dashboard/settings/api-keys), expose it as `ITERATETO_API_KEY` to the client process, then let the CLI write a project-scoped config. For hosted clients such as ChatGPT, add `https://iterateto.com/api/mcp` as a remote MCP server and sign in with OAuth; no API key is pasted into ChatGPT.

### ChatGPT

In ChatGPT Developer mode, open Plugins, select the plus button, and use these exact connection values. ChatGPT discovers iterateTo's OAuth login from the endpoint; you do not create or paste a personal key.

| ChatGPT field | Choose |
| --- | --- |
| Transport | Streaming / Streamable HTTP |
| Server URL | https://iterateto.com/api/mcp |
| Authentication | OAuth / automatic sign-in |
| Bearer token | Leave blank |

> **Warning:** If ChatGPT requires a bearer token and will not accept a blank value, cancel that modal. Do not paste an `itr_` key into ChatGPT. Reopen the connection from ChatGPT Plugins and choose the public URL flow so OAuth can be discovered automatically.

### Local coding tools

Set the secret in the environment that launches your client, then generate its config:

```bash
export ITERATETO_API_KEY=itr_your_secret_key
npx iterateto mcp init --client codex --host https://iterateto.com
```

Use `--client claude`, `cursor`, or `vscode` for another client. Generated files contain only an environment-variable reference, never the key itself.

## Connect with the CLI

`iterateto mcp init --client claude|codex|cursor|vscode` safely merges the iterateTo server into the client config. Use `--env-var NAME` when your team uses a different secret variable.

```bash
export ITERATETO_API_KEY=itr_your_secret_key
npx iterateto mcp init --client codex --host https://iterateto.com
```

To teach an agent the secure connect-and-verify workflow, install the optional cross-client skill: `npx skills add https://iterateto.com/mcp-skill.md`.

## Tools

| Tool | Description |
| --- | --- |
| `product_context_list_options` | Resolve the live member, team, product-area, and current-actor IDs required by write payloads. |
| `product_context_get` | Retrieve a bounded project context bundle, optionally filtered by record type. |
| `product_context_search` | Search context semantically when embeddings are configured, with deterministic lexical fallback. |
| `product_context_item_get` | Fetch one strategic artifact, outcome, opportunity, or solution-discovery record. |
| `product_context_create` | Create a validated Product Context record with an idempotency key. |
| `product_context_update` | Update a record with an idempotency key and optimistic version check. |
| `product_context_archive` | Archive one record; requires the administrative scope. |
| `feedback_list_projects` | List the projects in your organization. |
| `feedback_list` | List and filter feedback: project, status, kind, text search, tag; cursor-paginated. |
| `feedback_get` | Fetch one item in full — targets with selector candidates, notes, screenshot metadata. |
| `feedback_update` | Update status, priority, or tags (idempotent write). |
| `feedback_add_note` | Add an internal note with an idempotency key (≤ 2000 chars; REST allows up to 4000). |
| `feedback_stats` | Counts by status and kind, plus a per-day series. |

## Product Context resource

Clients that support MCP resources can read `iterateto://product/{projectId}/context`. The resource and tools use the same tenant checks and return only records belonging to the authenticated organization and requested project.

## Authentication & scopes

The endpoint accepts OAuth 2.1 access tokens and `itr_` personal access tokens. OAuth advertises its authorization-server and protected-resource metadata automatically, including PKCE and dynamic client registration for compatible remote clients. Hosted OAuth connections default to read-and-manage access; `product:admin` is never granted by default. Personal tokens can be read-only, read-and-manage, or full access. Available Product Context scopes are `product:read`, `product:write`, and `product:admin`; feedback has matching read/write scopes. Tools outside the token's scopes are not advertised.

Vector retrieval is optional. Set `AI_GATEWAY_API_KEY` and `PRODUCT_CONTEXT_EMBEDDING_MODEL` to use AI SDK embeddings with an Atlas Vector Search index. If embeddings or the index are unavailable, search explicitly reports that it used lexical fallback rather than pretending the result was semantic.

> **Note:** Writes require an idempotency key. Updates also accept `expectedVersion` to prevent overwriting a concurrent edit. Archiving is deliberately separated behind `product:admin`.

> **Warning:** Never paste an `itr_` key into chat, a shared link, a one-click deeplink, or a committed file. Generated configs reference an environment variable. Prefer OAuth for hosted or shared clients.

Ready-made agent workflows live in [Recipes](/docs/recipes).