> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retriever.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol (MCP)

> Connect Claude, ChatGPT, Cursor, or Codex to Retriever through the hosted MCP server. Same account, same credits, no HTTP client.

The **Model Context Protocol (MCP)** is an official Retriever integration, on par with the REST API. Your host agent (Claude, ChatGPT, Cursor, and others) calls typed **tools**; the server translates each call to the public API using your key.

You skip writing and maintaining an HTTP client for common flows: starting a list-building run, executing an atomic service, reading a table, or managing sequences.

> [!TIP]
>
> Coming from the REST [Quickstart](https://docs.retriever.run/quickstart.md)? The same account and `ret_live_…` key work on MCP. Credits match the API. Rate limits use the same per-key budgets, plus an `mcp` budget per JSON-RPC message.

## Endpoint

| Item | Value |
| - | - |
| URL | `{RETRIEVER_API_URL}/mcp` |
| Transport | **Streamable HTTP** (JSON-RPC 2.0), **POST** only |
| Authentication | OAuth 2.1 (recommended), `Authorization: Bearer ret_live_…`, or `?api_key=ret_live_…` on the MCP URL |

In production, the URL is `https://api.retriever.run/mcp`. For a local app-server, use `http://localhost:4320/mcp` (see the [Base URL](https://docs.retriever.run/index.md) table).

Without a valid token, the server returns `401` with a `WWW-Authenticate` header pointing to OAuth metadata (see below).

## Authentication

### OAuth 2.1 (recommended for every client that supports it)

Use the bare MCP URL (`{RETRIEVER_API_URL}/mcp`) with no key in the config. The client discovers OAuth metadata, opens the browser for consent, and receives a Retriever API key as the access token.

In the app, **Settings → MCP Integration** shows the server URL and the **Add to Claude** and **Add to Cursor** buttons.

### API key (fallback: Claude Desktop config file, scripts, clients without OAuth)

Create a key in the app: **Settings → API keys → Create API key**. Paste it into your MCP client configuration.

**Preferred:** send the key in the `Authorization: Bearer ret_live_…` header (see JSON examples below).

**One-liner URL:** some CLIs only accept a single URL. Append the key as a query parameter:

```
{RETRIEVER_API_URL}/mcp?api_key=ret_live_xxxxxxxxxxxxxxxx
```

> [!WARNING]
>
> The key acts on behalf of its creator, inside the organization the creator belongs to at the time of each request (workspaces, tables, shared credit balance). See [Multi-client](https://docs.retriever.run/recipes/multitenant.md#model-a-one-key-per-client-recommended) before connecting accounts of several clients. Do not commit it or expose it in an untrusted browser extension.

> [!WARNING]
>
> Query-string keys can appear in proxy logs, browser history, and referrer headers. Prefer the Bearer header when your client supports it; use `?api_key=` only for tools that cannot set custom headers.

### OAuth metadata (dynamic registration)

Remote clients that support OAuth 2.1 dynamically register and run the PKCE flow:

| Metadata | Path |
| - | - |
| Protected resource | `GET /.well-known/oauth-protected-resource/mcp` |
| Authorization server | `GET /.well-known/oauth-authorization-server` |
| Client registration | `POST /oauth/register` |
| Consent | `GET /oauth/authorize` then `POST /oauth/token` |

The issued access token is a **Retriever API key** named `MCP · <client name>`. You can view and revoke it under **Settings → API keys**.

* **One key per connection.** Each completed OAuth flow creates a new key. A new connection does not revoke the earlier keys, so two devices with the same client name both keep working.
* **Removing a connector does not revoke its key.** To cut access at once, revoke the key under **Settings → API keys**. Each reconnection adds a key with the same name. Unused keys are not expired automatically.
* **To reconnect**, run the connection again from your client, for example remove the Retriever connector and add it again. The client completes the OAuth flow and gets a new key. Many clients start this flow on their own when the server returns `401`.
* **Registration limits.** `POST /oauth/register` accepts 60 registrations per minute from one IP address. Over that, it returns `429` with `{"error": "rate_limited", "error_description": "Too many requests. Retry in N s."}`. The `/oauth/` endpoints refuse a body larger than 64 KiB with `413`. A `client_name` longer than 100 characters is cut to 100 characters. A redirect URI longer than 2048 characters gets `400`. Retriever deletes a registered client that has not completed a connection within 30 days. If the authorization page then says that the application is unknown, remove the Retriever connector from your client and add it again.
* **Connection limit.** One account can approve 20 OAuth connections in any 60-minute window. Over that, the consent page sends your client back with the OAuth error `temporarily_unavailable`, no code, and the wait in minutes (up to 1 hour). Start the connection again after that wait.

## Claude setup

Use one of the options below. Option 1 is the simplest.

### Option 1: custom connector

The connector works in Claude on the web, in the Claude desktop app, and in Claude Code when Claude Code is signed in with the same Claude account (not with an Anthropic API key).

1. In Claude, open **Customize → Connectors → + Add → Add custom connector**.
2. Name it Retriever, paste the URL `https://api.retriever.run/mcp`, and click **Continue** twice.
3. Keep a sign-in option (**Sign in now**, not **No sign in**), choose **Register automatically** for the OAuth client, and leave the headers empty.
4. Click **Add**, then **Connect**.
5. Sign in to Retriever if asked and click **Allow** (the button is labeled **Autoriser**).
6. In a chat, click **+ → Connectors** and turn on Retriever.

You do not paste a key. The OAuth flow creates one for you (see [OAuth metadata](#oauth-metadata-dynamic-registration)).

> [!NOTE]
>
> On a Team or Enterprise plan, only an Owner can add a custom connector, in **Organization settings → Connectors → Add → Custom → Web**. Each member then clicks **Connect** next to Retriever in **Customize → Connectors**.

### Option 2: Claude Desktop config file with an API key

Use this option only if you cannot add a custom connector. Node.js 18 or later must be installed on your computer.

1. In Claude Desktop, open **Settings → Developer → Edit Config**, or open the file directly:
   * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
2. If the file is empty or only contains `{}`, replace it with this block. If it already has an `mcpServers` section, add only the `retriever` entry inside it, with a comma after the entry before it:

```json theme={null}
{
  "mcpServers": {
    "retriever": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.retriever.run/mcp",
        "--header",
        "Authorization:${RETRIEVER_AUTH}"
      ],
      "env": {
        "RETRIEVER_AUTH": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

3. Replace `YOUR_API_KEY` with your full API key, then save.
4. Quit Claude Desktop completely (`Cmd + Q` on macOS; on Windows, right-click the Claude icon in the taskbar tray and click **Quit**), then open it again.

> [!NOTE]
>
> `mcp-remote` connects Claude Desktop to the hosted server. The key stays in `env` because Claude Desktop on Windows breaks `args` values that contain spaces.

> [!WARNING]
>
> Paste the full key only into the configuration file. Do not paste it into a chat.

### Claude Code from the terminal

If Retriever is already a connector in your Claude account and Claude Code is signed in with that account, it already works. Otherwise, add the server for all your folders:

```bash theme={null}
claude mcp add --transport http --scope user retriever https://api.retriever.run/mcp
```

Then start Claude Code with `claude`, type `/mcp`, select `retriever`, choose **Authenticate**, and sign in to Retriever in the browser. To use an API key instead, add `--header "Authorization: Bearer YOUR_API_KEY"` to the command (if you already added `retriever`, run `claude mcp remove retriever --scope user` first).

## ChatGPT setup

1. Open [**Plugins**](https://chatgpt.com/plugins), click **+ → Add custom MCP server**.
2. Name it Retriever and, under **Connection**, paste `https://api.retriever.run/mcp`. Keep **OAuth** for authentication. You can upload the Retriever logo as the icon (download it from **Settings → MCP Integration** in the app).
3. Click **I understand and want to continue**, then **Create as a plugin**.
4. Sign in to Retriever on the page that opens and click **Allow** (the button is labeled **Autoriser**). You do not paste a key.
5. In a new chat, type **@** and pick Retriever.

## Cursor setup

In the app, **Settings → MCP Integration → Add to Cursor** opens Cursor and installs the server. Confirm the install, then sign in to Retriever from **Customize** in the Cursor sidebar (in older versions: **Cursor Settings → Tools & MCP**).

To do it by hand, open `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project). If the file already has an `mcpServers` section, add only the `retriever` entry inside it. With OAuth, give only the URL:

```json theme={null}
{
  "mcpServers": {
    "retriever": {
      "url": "https://api.retriever.run/mcp"
    }
  }
}
```

With an API key, add the header, and only in `~/.cursor/mcp.json`: a project's `.cursor/mcp.json` is often committed with the code, and the key would go with it.

```json theme={null}
{
  "mcpServers": {
    "retriever": {
      "url": "https://api.retriever.run/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

If the API runs on your computer, use `{RETRIEVER_API_URL}/mcp` as the URL.

Restart Cursor. The Retriever tools show in the list (for example `credits`, `service_discover`, `retriever_build_list_start`).

## Codex setup

1. In the ChatGPT desktop app (Codex mode) or the Codex IDE extension, open **Settings → MCP servers → Add server**.
2. Name it `retriever`, choose **Streamable HTTP**, paste `https://api.retriever.run/mcp`, save, then click **Restart**. Do not add a key.
3. Click **Authenticate** next to `retriever`, sign in to Retriever, and click **Allow** (**Autoriser**).

With the Codex CLI:

```bash theme={null}
codex mcp add retriever --url https://api.retriever.run/mcp
codex mcp login retriever
```

With an API key, add this section to `~/.codex/config.toml` (delete any existing `[mcp_servers.retriever]` section first), then restart Codex:

```toml theme={null}
[mcp_servers.retriever]
url = "https://api.retriever.run/mcp"
http_headers = { Authorization = "Bearer YOUR_API_KEY" }
```

## Typical flow: list-building without HTTP

MCP equivalent of the [Quickstart](https://docs.retriever.run/quickstart.md):

1. **`credits`** — check balance before a paid run.
2. **`retriever_build_list_start`** — natural-language brief (for example “5 B2B SaaS startups in Lyon with websites”).
3. **`retriever_build_list_get`**: call it until `status` reaches a final value (`completed`, `failed` or `cancelled`). Each call waits up to 30 seconds for the run to end. Once the run is completed, the response includes the first 20 rows of each table. A run can take tens of minutes: after about 5 calls (a few minutes), give the user the `app_url` and check again later.
4. **`table_get_rows`**: further pages, or `include_cells: true` for citations and cell status.

Async tools (`retriever_build_list_*`, `retriever_research_*`) follow the same pattern as the API: **start → get → optional cancel**.

Runs started with `retriever_build_list_start` share your organization's run slots with the API: at most 5 runs execute at the same time by default. A further run stays `queued` and starts on its own when one ends. Do not start it again. See [Runs per organization](https://docs.retriever.run/concepts/runs.md#runs-per-organization).

## Atomic services (level 1)

For a one-off capability (email, company ID, scrape, and so on) without a run or table:

1. **`service_discover`**: browse or search for a service.
2. **`service_inspect`**: read `thingsToKnow` (what changes the cost or the outcome of a call), `inputSchema`, pricing (`unitCredits`), and billing policy.
3. **`service_execute`**: for one input of a fast service, send `{ "service": "<name>", "input": { ... } }` (`input` is the direct payload, not wrapped again).
4. **`service_batch_execute`** then **`service_batch_get`**: slow service (`getEmail`, `getPhoneNumber`, `webResearch`) or several inputs of any service: send every input in one list, even one for a slow service, then call `service_batch_get` until `status` is `completed` (each call waits up to 30 seconds by default).

MCP resources: embedded guides for host agents, one per kind of task.

| Resource | When the host reads it |
| - | - |
| `retriever://skills/retriever-services` | One service: the discover → inspect → execute loop, people at companies, contact lookups |
| `retriever://skills/retriever-workspace` | Lists: list-building runs, workspaces, tables, exclusions, scheduled runs |
| `retriever://skills/retriever-go` | One question answered without a table |
| `retriever://skills/retriever-outreach` | Sequences, enrollment, inbox. Listed only when the outreach tools are on |

## REST equivalence

| Need | MCP | REST |
| - | - | - |
| Credit balance | `credits` | `GET /credits` |
| List-building run | `retriever_build_list_start` / `_get` / `_list` / `_cancel` | `POST /v1/runs`, `GET /v1/runs/{id}`, `GET /v1/runs`, … |
| Go research | `retriever_research_start` / `_get` / `_cancel` | `POST /v1/go/runs`, … |
| Services | `service_discover`, `service_inspect`, `service_execute`, `service_batch_execute`, `service_batch_get`, `service_job_get` | `GET /services`, `POST /services/{name}`, `POST /v1/services/jobs/batch`, `GET /v1/services/jobs/batch/{id}`, `GET /v1/services/jobs/{id}` |
| Workspaces | `workspace_list`, `workspace_create` | `GET /v1/workspaces`, `POST /v1/workspaces` |
| Tables | `table_list`, `table_create`, `table_get`, `table_get_rows`, `table_export` | `/v1/…/tables` routes |
| Exclusions | `exclusion_list`, `exclusion_add`, `exclusion_remove` | `/v1/exclusions/{kind}` routes |
| Scheduled runs | `scheduled_run_list`, `scheduled_run_get`, `scheduled_run_create`, `scheduled_run_update`, `scheduled_run_set_status`, `scheduled_run_run_now`, `scheduled_run_list_runs`, `scheduled_run_delete` | `/v1/scheduled-runs` routes |
| Plays | `play_list`, `play_get`, `play_create`, `play_update`, `play_list_versions`, `play_restore_version`, `play_launch`, `play_set_status`, `play_list_leads`, `play_lead_accept`, `play_lead_reject`, `play_lead_replace`, `play_lead_rewrite_message`, `play_lead_save_message`, `play_rewrite_step_instructions`, `play_move_leads`, `play_list_news`, `play_proposal_decide`, `play_delete` | `/v1/plays` routes |
| Sequences and inbox | `sequence_*`, `inbox_*`, `sender_*` | Outreach routes (same account) |

Full tool reference: [MCP tool catalog](https://docs.retriever.run/mcp/tools.md).

## Limits and behavior

* **Stateless**: each POST builds an ephemeral MCP session; no persistent SSE stream (`GET /mcp` returns `405`).
* **Credits**: billed tool calls use the same layer as the API; ledger source is `mcp`.
* **Rate limits**: per-key limits apply like the REST API ([Rate limits](https://docs.retriever.run/concepts/rate-limits.md)). Each JSON-RPC message costs one unit of the key's `mcp` budget, 600 per minute by default. The API calls that a tool makes count in their own classes. A JSON-RPC batch (several messages in one HTTP request; most clients never send one) holds at most 10 messages; a larger one gets `400` with JSON-RPC error `-32600` before anything runs. This does not limit `service_batch_execute`, which takes 1 to 100 inputs. A body larger than 10 MiB gets `413` with error `-32600`, and a body that is not JSON gets `400` with error `-32700`.
* **Shared IP addresses**: all claude.ai users reach Retriever from shared Anthropic IP addresses. A `429` from the failed-authentication guard clears within 10 seconds. See [Failed authentication](https://docs.retriever.run/concepts/rate-limits.md#failed-authentication).
* **Cancellation**: when your client closes the HTTP request (timeout, stop button, closed tab), Retriever stops the API calls of the tool in progress, like a closed REST request. This includes a synchronous Go search and a service call. Credits already charged for provider calls that answered before the hang-up stay charged. A run that already started (`retriever_build_list_start`, `retriever_research_start`) keeps running.
* **Errors**: tools return structured JSON; key your agent off error codes, not free-form text.

## Next steps

* [MCP tool catalog](https://docs.retriever.run/mcp/tools.md) — all tools by domain.
* [REST Quickstart](https://docs.retriever.run/quickstart.md) — same journey with `curl`.
* [Runs](https://docs.retriever.run/concepts/runs.md) — statuses, artifacts, and output tables.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.