Connect

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. 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 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.

{
  "mcpServers": {
    "reply": {
      "type": "http",
      "url": "https://mcp.reply.io/",
      "headers": { "Authorization": "Bearer YOUR_REPLY_API_KEY" }
    }
  }
}

Claude Code, one line:

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 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 proxy and pass your key in the Authorization header:

{
  "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:

Open an HTTP connection to https://mcp.reply.io/.
Send a JSON-RPC initialize with your protocol version and client info.
Send the notifications/initialized notification if your client library requires it.
Call tools/list to discover tools, their JSON schemas, and their annotations.
Call tools/call with a tool name and an argument object.

initialize

{
  "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:

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/):

{
  "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). 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:

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.

Reply MCP overview — what the server exposes
Tool reference — all 70 tools
Connecting Reply MCP to your AI model (Help Center)

Get started

For agents

1) Get your API key

2) Add it to your client

Header auth (recommended)

OAuth (clients without header auth)

Fallback: `mcp-remote` (clients without native remote MCP)

Handshake

Authentication details

Unsupported keys

Rate limits

​1) Get your API key

​2) Add it to your client

​Header auth (recommended)

​OAuth (clients without header auth)

​Fallback: mcp-remote (clients without native remote MCP)

​Handshake

​Authentication details

​Unsupported keys

​Rate limits

​Related

1) Get your API key

2) Add it to your client

Header auth (recommended)

OAuth (clients without header auth)

Fallback: `mcp-remote` (clients without native remote MCP)

Handshake

Authentication details

Unsupported keys

Rate limits

Related