MCP

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

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:

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, 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 and manage your ReplyNodes organization at 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 or the full protocol at 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:

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

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.

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.