> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reply.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect
> Add Reply MCP to Claude, Cursor, or any MCP-compatible client.
Connect Reply MCP to your AI client in two steps: get your API key, then point your client at
`https://mcp.reply.io/`.
## 1) Get your API key
Reply MCP authenticates with your Reply.io **personal API key**. Create or copy one under
**Settings → API Key** in the [Reply dashboard](https://run.reply.io).
A personal API key is the preferred credential because it's **scoped**: you grant it only the
permissions your agent needs, and it can call only the tools those permissions cover. A scope is
a permission such as `contacts:read` or `sequences:operate`, grouped by area (contacts,
sequences, inbox, tasks, channels, AI SDR), so you can give an agent exactly the reach it needs
and nothing more. Set the scopes on the key in **Settings → API Key**; see
[Scopes](/api-reference/authentication#scopes) for the full list.
The MCP connection URL is `https://mcp.reply.io/`. You can also open it in the app under
**Execution → Integrations → Reply MCP Server → Configure**, which is where you set up and
configure the MCP connection.
Treat your API key like a password. Don't share it in public repositories, screenshots, or
chat messages. If it's exposed, generate a new API key in Reply.
## 2) Add it to your client
### Header auth (recommended)
Most modern MCP clients support remote Streamable HTTP servers with header auth. Point the client
at `https://mcp.reply.io/` and pass your key in the `Authorization` header as a bearer token.
```json theme={null}
{
"mcpServers": {
"reply": {
"type": "http",
"url": "https://mcp.reply.io/",
"headers": { "Authorization": "Bearer YOUR_REPLY_API_KEY" }
}
}
}
```
**Claude Code**, one line:
```bash theme={null}
claude mcp add --transport http reply https://mcp.reply.io/ \
--header "Authorization: Bearer YOUR_REPLY_API_KEY"
```
### OAuth (clients without header auth)
Some clients don't let you set an API key or custom headers — typically the **UI / desktop apps**
of Claude, ChatGPT, and Codex, where you add a connector by URL only. For those, use OAuth: add
Reply MCP as a remote/custom connector with the URL `https://mcp.reply.io/` and authorize when
prompted — no key to copy or store.
OAuth grants access to the **full tool catalog** — it's equivalent to an API key with **all
scopes**, and there's no per-scope control over an OAuth connection. So whenever your client does
support header auth, prefer a scoped personal API key (above) to limit what the agent can do.
Some OAuth clients don't support Client ID Metadata Documents (CIMD) and fall back to Dynamic
Client Registration, which is allow-listed on our side. If your client reports an allow-list or
registration error when connecting, let us know in the [community Slack](/slack) and we'll
review it.
### Fallback: `mcp-remote` (clients without native remote MCP)
If your client only supports local (stdio) MCP servers, bridge to the remote server with the
[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) proxy and pass your key in the
`Authorization` header:
```json theme={null}
{
"mcpServers": {
"reply": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.reply.io/",
"--header",
"Authorization: Bearer YOUR_REPLY_API_KEY"
]
}
}
}
```
Passing credentials in the URL (for example `?api_key=...`) is not supported. Always
authenticate with the `Authorization` bearer header.
## Handshake
Once connected, MCP clients drive the standard flow automatically. If you're building a client by
hand:
1. Open an HTTP connection to `https://mcp.reply.io/`.
2. Send a JSON-RPC `initialize` with your protocol version and client info.
3. Send the `notifications/initialized` notification if your client library requires it.
4. Call `tools/list` to discover tools, their JSON schemas, and their annotations.
5. Call `tools/call` with a tool name and an argument object.
```json initialize theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": { "name": "your-client", "version": "1.0.0" }
}
}
```
No `Mcp-Session-Id` is required — `initialize` and `tools/list` work without a session.
## Authentication details
An unauthenticated call returns `401 Unauthorized` with an OAuth challenge header:
```http theme={null}
WWW-Authenticate: Bearer resource_metadata="https://mcp.reply.io/.well-known/oauth-protected-resource/"
```
The published protected-resource metadata (`GET /.well-known/oauth-protected-resource/`):
```json theme={null}
{
"resource": "https://mcp.reply.io",
"authorization_servers": ["https://oauth.sandbox.replyapp.io"],
"bearer_methods_supported": ["header"],
"scopes_supported": ["reply-web-api", "mcp:tools"]
}
```
For most agents a scoped personal API key is the recommended path — it gives the finest-grained
control over what the agent can do (see [Scopes](/api-reference/authentication#scopes)). The
OAuth metadata exists for clients (e.g. Claude custom connectors) that prefer a discovery-based
flow; OAuth grants the **full tool catalog** (all scopes), so prefer a scoped personal API key
when you want to limit an agent's reach.
### Unsupported keys
Reply MCP is a single-user connection, so **act-on-behalf API keys are not supported** —
including team-level **Team keys** and **Organization API keys**. These are designed to make
requests on behalf of other users, which a single-user connection doesn't provide. Use a
personal API key or OAuth instead.
## Rate limits
The server enforces an hourly window (\~3000 requests/hour). Every response carries the current
budget:
```http theme={null}
X-Rate-Limit-Limit: 1h
X-Rate-Limit-Remaining: 2997
X-Rate-Limit-Reset: 2026-07-05T00:00:00.0000000Z
```
On `429`, back off until the `X-Rate-Limit-Reset` timestamp before retrying.
## Related
* [Reply MCP overview](/mcp/overview) — what the server exposes
* [Tool reference](/mcp/tools) — all 70 tools
* [Connecting Reply MCP to your AI model (Help Center)](https://support.reply.io/en/articles/12955018-connecting-reply-mcp-to-your-ai-model)