# MCP

> Connect read-only ReplyNodes tools to MCP clients.

Source page: https://docs.replynodes.com/docs/mcp

# MCP

ReplyNodes provides one enterprise MCP application, powered by `mcp-use`, at:

```text
https://mcp.replynodes.com/mcp
```

The same application serves both the human-readable landing page and the
Streamable HTTP protocol. It supports native Better Auth MCP OAuth for
interactive clients and ReplyNodes API keys for headless or manually
configured clients:

```text
GET  /mcp  -> mcp-use landing page
POST /mcp  -> MCP initialize, tools/list, and tools/call
```

### Interactive OAuth

An MCP client that supports OAuth can start its authorization flow from the
remote server URL. Better Auth is the OAuth authority at
[`https://auth.replynodes.com`](https://auth.replynodes.com), and the MCP
scope is `mcp:read`. The client owns the browser redirect and PKCE flow; do not
copy an access token into configuration or prompts. Sign in or manage your
[`https://platform.replynodes.com/sign-in`](https://platform.replynodes.com/sign-in) and manage your ReplyNodes organization at [`https://platform.replynodes.com/api-keys`](https://platform.replynodes.com/api-keys).

OAuth access is organization-scoped. The client does not provide an
organization id; ReplyNodes resolves the organization from the authenticated
identity and enforces credits, entitlements, metering, and read-only access.

## Connect

For a headless agent without a key, follow the [agent claim flow](https://docs.replynodes.com/docs/auth)
or the full protocol at [https://replynodes.com/auth.md](https://replynodes.com/auth.md)
first. For headless, CI, or clients without OAuth support, configure the remote server
URL and store a ReplyNodes API key as a secret. The exact UI or config file
varies by client; use the client's equivalent of:

```json
{
  "url": "https://mcp.replynodes.com/mcp",
  "headers": {
    "Authorization": "Bearer ${REPLYNODES_API_KEY}"
  }
}
```

The placeholder is illustrative configuration syntax: use the secret mechanism
documented by your client, and never paste a real key into a committed file.

## Credits and package pricing

Authenticated MCP calls use the same prepaid package credits as the REST API.
The current ReplyNodes packages are:

| Package | Included credits | Price |
| --- | ---: | ---: |
| Free | 500 one-time credits | Free |
| Developer | 10,000 credits/month | $19/month |
| Pro | 100,000 credits/month | $99/month |

Per-call credit usage is determined by the canonical capability and pricing
contract; the MCP client cannot set or override a price. Review package access
Review package access and organization billing from [`https://platform.replynodes.com/api-keys`](https://platform.replynodes.com/api-keys).

## Tool contract

The MCP tool catalog is generated from the canonical runtime capabilities
OpenAPI contract at `services/replynodes-fetcher/internal/gateway/capabilities.openapi.json`.
Provider tool arguments map to read-only REST `GET` operations; monitor tool
arguments map to the lifecycle operations under `/v1/monitors`, merged into the
MCP catalog from the monitor contract at `api-docs/replynodes-fetcher.openapi.json`.
Company Changes is merged from the same contract, but MCP exposes exactly four
read tools: `get_company_events`, `get_company_history`,
`get_recent_company_events`, and `get_company_intelligence`. No CCI write tool
is discoverable.

Provider tool calls are forwarded to `https://api.replynodes.com`. Monitor and
Company Changes calls whose path begins `/v1/monitors`, `/v1/watches`,
`/v1/events`, `/v1/entities`, or `/v1/intelligence` are forwarded to the private monitor
service origin configured by `MONITOR_API_ORIGIN`; the signed gateway/OAuth
handoff is preserved. The configured
origin is enforced fail-closed before any caller `Authorization` header is
forwarded: only loopback/private hosts are accepted (`localhost`, `*.localhost`,
or a private/loopback/link-local IP literal — IPv4 and IPv6, including
IPv4-mapped IPv6 such as `::ffff:7f00:1`, excluding the cloud-metadata band
169.254.169.0/24 including 169.254.169.254); public hosts and unapproved DNS
names are rejected, so the private monitor service must be reachable by private
IP or localhost. The public OpenAPI server URL remains
`https://api.replynodes.com` for external API consumers. The Go gateway remains
the authority for authentication, OrganizationID, entitlement, credits,
metering, rate limits, cache, provider execution, and normalized errors. The
TypeScript MCP application does not duplicate those rules. `MONITOR_API_ORIGIN`
is resolved lazily, only when a monitor tool call needs it: a deployment
without monitor integration keeps serving every provider tool normally, and an
unconfigured or unapproved monitor origin fails only the monitor call closed
(`monitor_api_misconfigured`) before any caller `Authorization` is forwarded.

The PDF capability is the sole MCP PDF tool, named `read_document`. It accepts
one top-level `url` containing a public PDF URL and forwards the canonical
`POST https://pdf.replynodes.com/` request. Its description supports discovery
for PDF to Markdown, read PDF, PDF for AI agents, extract PDF text, and PDF
context. The public PDF contract remains authoritative for its limits and
errors.

### Monitor tool credentials

Standard MCP OAuth (`mcp:read`) maps only to the monitor service's read
operations (`monitor_list`, `monitor_get`, `monitor_changes`, `monitor_runs`)
and the four CCI read tools through the `monitors:read` scope. The write tools (`monitor_create`,
`monitor_update`) require `monitors:write`, which the standard MCP OAuth path
never grants: use a ReplyNodes `rn_test_*` / `rn_live_*` API key in the
`Authorization` header for monitor writes. An OAuth-authenticated client that
calls a write tool receives `403 forbidden_scope`; that is the intended
fail-closed behavior, not a transient error.

Monitor HTTP calls are rate-limited per organization by the monitor service
itself — 60 requests/min for the write bucket (create and update, where update
also covers pausing) and 300 requests/min for the read bucket
(get/list/history) by default — independent of the gateway's provider quotas.
Exhausted windows return `429 rate_limited` with `Retry-After` and
`X-RateLimit-*` headers; when the limiter itself cannot reach its database the
call fails closed with `503 degraded`. Scheduled monitor execution is governed
by the monitor scheduler and is not counted against those HTTP limits.

Two prerequisites for the public monitor contract remain outside this
repository and are not implemented here: the edge/router must map
`https://api.replynodes.com/v1/monitors` to the privately bound monitor
service, and the control plane that issues `rn_*` API-key scopes must mint
`monitors:read`/`monitors:write`. Until the scope issuance ships, API-key
monitor calls fail closed with `403 forbidden_scope`.

## Verify

Use the client's MCP initialize flow, then inspect `tools/list` and call one
harmless read-only tool. Authentication is forwarded to the REST gateway; an
unauthenticated request cannot execute a tool.

Every MCP tool call requires a ReplyNodes API key or OAuth access token,
including discovery tools and tools whose stable names begin with
`anonymous_`. Those names refer to their REST routes; they do not grant
credential-free MCP execution. Tool descriptions reflect the MCP credential
requirement even when the underlying REST endpoint permits public access.

The available capability groups can change with the gateway contract. Read the
canonical capabilities/OpenAPI artifact before relying on a particular tool.

## Troubleshooting

- `401`: confirm the client completed native Better Auth MCP OAuth, or that it
  sends an `Authorization` header with a valid ReplyNodes API key.
- `404`: confirm the URL is exactly `https://mcp.replynodes.com/mcp`.
- `400`: validate the JSON-RPC request, MCP protocol version, tool name, and
  declared arguments.
- `429`: honor `Retry-After` and reduce concurrency.