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

# Connectors

> Add Revcenter to Claude and ChatGPT from the browser, or to your own LLM or agent with an API key: one URL.

> Agents: the full documentation index is at [/llms.txt](https://docs.revcenter.ai/llms.txt).

Revcenter runs a hosted MCP server. Add it to your AI app as a custom connector and the app can draft
criteria, run searches and read shortlists in your workspace, with nothing to install.

```text theme={null}
https://api.revcenter.ai/mcp
```

When you add it, the app sends you to Revcenter to sign in. Pick the workspace to connect and click
**Authorize**. Any member, Admin or Editor, connects apps, and the workspace needs a plan or credits. The app acts
as you, with your role: an Editor's connection sees only their own projects.

## Add it to your app

> [tab] Claude
>
> 1. Open **Customize → Connectors**, click **+ Add** and choose **Add custom connector**. On Team and
>    Enterprise, an owner adds it first under **Organization settings → Connectors** (**Add → Custom → Web**),
>    then members click **Connect**.
> 2. Name it Revcenter, paste the URL and click **Continue**. Keep the detected sign-in settings and click
>    **Add**.
> 3. Click **Connect**, sign in to Revcenter and pick the workspace.
>
> Works in Claude on the web, desktop and mobile. On the Free plan you can add one custom connector.

> [tab] ChatGPT
>
> 1. In ChatGPT on the web, open **Plugins**, click **+** and choose **Add custom MCP server**. Account and
>    workspace policies decide who can add one: on Business, Enterprise and Edu, a workspace admin turns on
>    developer mode first (**Workspace settings → Permissions & roles**).
> 2. Name it Revcenter, paste the URL under **Connection** and choose **OAuth** for authentication.
> 3. Accept the warning, select **Create as a plugin**, then sign in to Revcenter when asked and pick the
>    workspace.

Any other MCP client that speaks Streamable HTTP and OAuth can connect the same way. A client that can't sign
in through a browser uses an API key instead: see [Custom LLMs and agents](#custom-llms-and-agents).

## Custom LLMs and agents

Model APIs, IDEs and agent frameworks can't open a browser to sign in. Give them the same URL and a Revcenter
API key as a bearer token:

```text theme={null}
URL:     https://api.revcenter.ai/mcp
Header:  Authorization: Bearer rvc_live_…
```

### Get an API key

Any member creates one under **Settings → Integrations → API** ([Authentication](https://docs.revcenter.ai/authentication.md)); it acts as them, with their role. A key made
there holds every agent scope (`projects`, `searches`, `shortlists` and `webhooks`, each `:read` and
`:write`), which is what the tools need. A key with fewer scopes lists only the tools its scopes reach, and a
call beyond them is refused with `insufficient_scope`, exactly as the [API](https://docs.revcenter.ai/api-reference/introduction.md) refuses it.

The key works at `/mcp` as it does at `/v1`: the same plan rule (`plan_required` without a plan or credits),
rate limits, expiry and revocation, and its tool calls appear in the workspace's API logs under the key's
name. Send it only in the `Authorization` header; a key in the URL is never read. Keep it in an environment
variable or secret store, never in code or a prompt.

### OpenAI Responses API

The `mcp` tool sends `authorization` to the server as the bearer token.

```bash curl theme={null}
curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "tools": [{
      "type": "mcp",
      "server_label": "revcenter",
      "server_url": "https://api.revcenter.ai/mcp",
      "authorization": "'"$REVCENTER_API_KEY"'",
      "require_approval": "never"
    }],
    "input": "List my Revcenter projects."
  }'
```

```python Python theme={null}
import os
from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-6-astra",
    tools=[{
        "type": "mcp",
        "server_label": "revcenter",
        "server_url": "https://api.revcenter.ai/mcp",
        "authorization": os.environ["REVCENTER_API_KEY"],
        "require_approval": "never",
    }],
    input="List my Revcenter projects.",
)
print(response.output_text)
```

### Anthropic Messages API

The MCP connector is in beta: send the `anthropic-beta: mcp-client-2025-11-20` header (or `betas` in the SDK),
name the server in `mcp_servers` with the key as `authorization_token`, and enable its tools with an
`mcp_toolset` entry.

```bash curl theme={null}
curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 2000,
    "messages": [{"role": "user", "content": "List my Revcenter projects."}],
    "mcp_servers": [{
      "type": "url",
      "url": "https://api.revcenter.ai/mcp",
      "name": "revcenter",
      "authorization_token": "'"$REVCENTER_API_KEY"'"
    }],
    "tools": [{"type": "mcp_toolset", "mcp_server_name": "revcenter"}]
  }'
```

```python Python theme={null}
import os
import anthropic

client = anthropic.Anthropic()
response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=2000,
    messages=[{"role": "user", "content": "List my Revcenter projects."}],
    mcp_servers=[{
        "type": "url",
        "url": "https://api.revcenter.ai/mcp",
        "name": "revcenter",
        "authorization_token": os.environ["REVCENTER_API_KEY"],
    }],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "revcenter"}],
    betas=["mcp-client-2025-11-20"],
)
print(response.content)
```

### Cursor and VS Code

```json Cursor (~/.cursor/mcp.json) theme={null}
{
  "mcpServers": {
    "revcenter": {
      "url": "https://api.revcenter.ai/mcp",
      "headers": { "Authorization": "Bearer ${env:REVCENTER_API_KEY}" }
    }
  }
}
```

```json VS Code (.vscode/mcp.json) theme={null}
{
  "inputs": [
    { "type": "promptString", "id": "revcenter-key", "description": "Revcenter API key", "password": true }
  ],
  "servers": {
    "revcenter": {
      "type": "http",
      "url": "https://api.revcenter.ai/mcp",
      "headers": { "Authorization": "Bearer ${input:revcenter-key}" }
    }
  }
}
```

Cursor reads `${env:REVCENTER_API_KEY}` from your shell environment; VS Code asks for the key once and stores
it.

### Any other MCP client

Windsurf, LangChain's MCP adapters and any other client that speaks MCP over Streamable HTTP connect the same
way: the URL, transport `streamable_http` (or `http`), and the header `Authorization: Bearer <key>`. The
server is stateless: POST JSON-RPC and each request is answered on its own, as JSON; there is no session id
and no GET stream.

Paid actions still ask first: a launch returns `pending_approval` with a proposal and runs only when your agent
calls `apply_proposal`, so have it show the proposal to a person before it does.

## What it can do

The same tools as the [local MCP server](https://docs.revcenter.ai/tools/mcp.md), with two differences:

* **No file exports.** A chat can't save files, so the export tools are left out. Page through people with
  `list_people`, `list_search_records` and `list_candidates`, and send a client `get_share_link`.
* **Spending asks first.** `launch_search`, `launch_searches` and `expand_search` reserve credits;
  `publish_shortlist` and `send_shortlist_email` reach the client; `delete_project` can't be undone. Each one
  runs nothing at first: it returns `pending_approval` with a proposal and what to show you. The app runs it
  with `apply_proposal` only after you agree. Repeating a launch returns the same search and never pays twice.

Searches take minutes. Ask the app to wait for the search (`wait_for_search` waits up to three minutes a
call), then to list everyone scoring 80 or more.

## Disconnect

**Settings → Integrations → Connectors** lists the connected apps. **Revoke** stops one at once. Each connection is
also an API key in **Settings → Integrations → API**, named after the app; revoking it there does the same.
Connecting the same app again replaces its earlier connection.

## Security

* Sign-in uses OAuth 2.1 with PKCE. The app never sees your password or an API key. Custom LLMs and agents
  use an API key you give them instead; revoke it in **Settings → Integrations → API** to cut them off.
* An access token lasts an hour and works only at `https://api.revcenter.ai/mcp`, for the one workspace you
  picked. The app renews it with a refresh token that changes on every use; a refresh token used twice
  disconnects the app.
* Every call runs through the Revcenter API as that connection: the same permissions, plan, credits and
  rate limits as an API key.


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