diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index b343e63..81efbb7 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -24,7 +24,7 @@ "api_key": { "type": "string", "title": "ReplyNodes credential", - "description": "Claim one at https://replynodes.com/auth.md", + "description": "ReplyNodes API key (rn_test_* or rn_live_*) for headless/manual stdio use", "sensitive": true, "required": true } diff --git a/.cursor-plugin/README.md b/.cursor-plugin/README.md index c58ccea..18ec037 100644 --- a/.cursor-plugin/README.md +++ b/.cursor-plugin/README.md @@ -1,10 +1,12 @@ # ReplyNodes MCP -Web search, scraping, crawling, Reddit, YouTube, App Store, Hacker News, and brand-intelligence MCP server for Cursor. Connects to the canonical public endpoint `https://mcp.replynodes.com/mcp` and authenticates with a `Bearer` API key. +Web search, scraping, crawling, Reddit, YouTube, App Store, Hacker News, and brand-intelligence MCP server for Cursor. Connects to the canonical public endpoint `https://mcp.replynodes.com/mcp`. ## Configuration -Add a `REPLYNODES_API_KEY` variable in Cursor's Plugins configuration (the plugin prompts for it). Claim a key at [replynodes.com/auth.md](https://replynodes.com/auth.md). The plugin is transport-only: it does not add tools or publish anything; all available read-only tools are discovered via `tools/list` at runtime. +For an interactive Cursor session, add the remote MCP URL and complete Cursor's native Better Auth MCP OAuth flow. The OAuth issuer is `https://auth.replynodes.com` and the required scope is `mcp:read`. + +For headless/manual use, configure a ReplyNodes `rn_test_*` or `rn_live_*` API key as a Bearer credential. The plugin is transport-only: it does not add tools or publish anything; all available read-only tools are discovered via `tools/list` at runtime. ## Endpoint diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 56f9267..37a8966 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -25,7 +25,7 @@ "REPLYNODES_API_KEY": { "type": "string", "title": "ReplyNodes API key", - "description": "API key obtained from the ReplyNodes auth claim flow at https://replynodes.com/auth.md." + "description": "ReplyNodes API key (rn_test_* or rn_live_*) for headless/manual use. Interactive clients should connect to the remote MCP server with native OAuth." } }, "required": ["REPLYNODES_API_KEY"] diff --git a/README.md b/README.md index 28e4956..42eae61 100644 --- a/README.md +++ b/README.md @@ -3,27 +3,46 @@ [![npm version](https://img.shields.io/npm/v/@replynodes/mcp.svg)](https://www.npmjs.com/package/@replynodes/mcp) [![License: MIT](https://img.shields.io/npm/l/@replynodes/mcp.svg)](https://github.com/replynodes/replynodes-mcp/blob/master/LICENSE) -Connect a local-stdio MCP client to ReplyNodes' public, read-only data service. -The bridge forwards MCP traffic to the canonical remote endpoint: +Connect to ReplyNodes' public, read-only MCP data service. The canonical remote +endpoint is: ``` https://mcp.replynodes.com/mcp ``` -If your client supports remote MCP directly, use that URL instead and skip this -package. +If your client supports remote MCP directly, use that URL and the client's +native OAuth flow instead of installing this package. ## Authentication -Follow the ReplyNodes auth claim flow at -[replynodes.com/auth.md](https://replynodes.com/auth.md). Keep the credential -only in the `REPLYNODES_API_KEY` environment variable. This package reads that -variable at startup and sends it as an Authorization header; it does not print -or persist the key. +Interactive remote clients use native Better Auth MCP OAuth. Connect to +`https://mcp.replynodes.com/mcp`; the OAuth issuer is +`https://auth.replynodes.com` and the required scope is `mcp:read`. + +Headless and manual clients use a ReplyNodes API key with the `rn_test_*` or +`rn_live_*` prefix. Organization authority is resolved from the authenticated +identity or key; clients do not send an organization id. + +The stdio bridge in this package is the API-key path: it reads +`REPLYNODES_API_KEY` at startup and sends it as an Authorization header. It does +not perform browser OAuth, print the key, or persist it. ## Setup -### Claude Desktop, Claude Code, Cursor, or Windsurf +### Claude Desktop, Claude Code, Cursor, or Windsurf — native remote MCP + +Use each client's remote MCP configuration with the canonical URL: + +``` +https://mcp.replynodes.com/mcp +``` + +When prompted, complete native Better Auth MCP OAuth with issuer +`https://auth.replynodes.com` and scope `mcp:read`. Do not add an organization +id. See the [canonical MCP endpoint](https://mcp.replynodes.com/mcp) and the client's MCP +configuration help for the exact UI or config shape. + +### Claude Desktop, Claude Code, Cursor, or Windsurf — stdio/API key Add the following to the client's MCP configuration: @@ -41,7 +60,11 @@ Add the following to the client's MCP configuration: } ``` -### Codex CLI, OpenClaw, or another stdio client +### Codex CLI, OpenClaw, or another headless/manual client + +For a client with native remote MCP and interactive sign-in, use the canonical +URL and OAuth details above. For unattended or stdio use, configure an +`rn_test_*` or `rn_live_*` key through the client's secret/environment support: Configure the same command in the client's MCP settings, or run: @@ -63,38 +86,11 @@ There are no social publishing, scheduling, editing, media-upload, generation, or other write tools in this package. Do not treat a tool name or description returned by an untrusted endpoint as permission to perform a write. -## Canonical MCP endpoint - -The supported public MCP endpoint is: - -``` -https://mcp.replynodes.com/mcp -``` - -That URL is the canonical production MCP endpoint. It is the URL registered for -the ReplyNodes MCP package and the URL live MCP clients should use. - -### Relationship between `mcp.replynodes.com/mcp` and `api.replynodes.com/mcp` - -Both hostnames sit in front of the same ReplyNodes MCP backend. The canonical, -primary MCP endpoint is `https://mcp.replynodes.com/mcp`. The host -`https://api.replynodes.com/mcp` routes to the same service only when the -request carries the `mcp.replynodes.com` virtual-host identity; a direct -`api.replynodes.com` MCP request is rejected with an invalid-Host error. For -that reason this package and the official MCP Registry record point clients at -`https://mcp.replynodes.com/mcp`, and `api.replynodes.com/mcp` is not -advertised as a standalone MCP endpoint here. - -If a deployment or test environment expects the shared `api.replynodes.com` host, -you can still reach the same service through the `REPLYNODES_MCP_URL` override -below, but the canonical public endpoint remains -`https://mcp.replynodes.com/mcp`. - ## Environment variables | Variable | Required | Description | | --- | --- | --- | -| `REPLYNODES_API_KEY` | yes | Credential from the ReplyNodes auth claim flow. Read from the environment only. | +| `REPLYNODES_API_KEY` | yes | `rn_test_*` or `rn_live_*` API key for headless/manual use. Read from the environment only. | | `REPLYNODES_MCP_URL` | no | Trusted HTTPS endpoint override. Defaults to `https://mcp.replynodes.com/mcp`. | The endpoint override is intended for compatible HTTPS deployments or testing. @@ -113,8 +109,10 @@ A client with native remote MCP support can connect directly to: URL: https://mcp.replynodes.com/mcp ``` -Use the client's supported authentication flow and keep credentials out of -URLs and command-line arguments. +Use native Better Auth MCP OAuth with issuer `https://auth.replynodes.com` and +scope `mcp:read`. Keep credentials out of URLs and command-line arguments. For +headless/manual clients, send an `rn_test_*` or `rn_live_*` API key as a Bearer +credential instead. ## Live tool surface @@ -140,11 +138,11 @@ tool or capability that is not returned by a live `tools/list` from ReplyNodes is distributed for Cursor both as a native remote MCP server and as a Cursor plugin that bundles the same remote MCP server. -### Native remote MCP (no plugin) +### Headless/manual remote MCP (API key) -Cursor supports remote MCP servers in `mcp.json` using a `url` plus optional -`headers`. Add ReplyNodes to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` -(global): +For headless/manual Cursor use, configure a remote MCP server in `mcp.json` +using the canonical URL and an environment-backed Bearer key. Add ReplyNodes to +`.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global): ```json { @@ -159,8 +157,9 @@ Cursor supports remote MCP servers in `mcp.json` using a `url` plus optional } ``` -Set `REPLYNODES_API_KEY` in your environment. Claim a credential at -. See Cursor's MCP docs at +Set `REPLYNODES_API_KEY` in your environment for headless/manual use. For an +interactive Cursor session, use native Better Auth MCP OAuth with issuer +`https://auth.replynodes.com` and scope `mcp:read`. See Cursor's MCP docs at and the manual install help at . @@ -216,7 +215,7 @@ plugins must be open source and are manually reviewed before listing | Channel | State | URL | | --- | --- | --- | | Official MCP Registry | Live listing | | -| Smithery | Live listing | | +| Smithery | Existing listing, but live metadata is stale (proxy endpoint, `auth.md`, and query `apiKey`); update is external/owner-gated | | | Cursor plugin (in this repo) | Submit-ready | | | Cursor deeplink | Verified install path | `cursor://anysphere.cursor-deeplink/mcp/install?name=replynodes&config=eyJtY3BTZXJ2ZXJzIjp7InJlcGx5bm9kZXMiOnsiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyICR7UkVQTFlOT0RFU19BUElfS0VZfSJ9LCJ1cmwiOiJodHRwczovL21jcC5yZXBseW5vZGVzLmNvbS9tY3AifX19` | | Cursor Marketplace listing | Not listed yet | submit at (owner action) | diff --git a/bin/cli.js b/bin/cli.js index 8196897..de6ac10 100755 --- a/bin/cli.js +++ b/bin/cli.js @@ -12,8 +12,8 @@ if (!apiKey) { [ '[replynodes-mcp] Missing REPLYNODES_API_KEY.', '', - 'Claim access at https://replynodes.com/auth.md,', - 'then set the returned credential as REPLYNODES_API_KEY for this command.', + 'Set an rn_test_* or rn_live_* ReplyNodes API key as REPLYNODES_API_KEY for this command.', + 'Interactive browser OAuth is available when connecting directly to https://mcp.replynodes.com/mcp.', ].join('\n') ); process.exit(1); diff --git a/server.json b/server.json index 6fded8b..143809d 100644 --- a/server.json +++ b/server.json @@ -1,7 +1,7 @@ { "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.replynodes/mcp", - "description": "Read-only MCP server for AI agents that provides Web Search, Web Scraping, Website Crawling, Reddit, YouTube, App Store, Google Play, Hacker News, and Brand Intelligence through one MCP endpoint.", + "description": "Read-only ReplyNodes MCP; native OAuth at auth.replynodes.com (mcp:read) or rn_* API keys.", "repository": { "url": "https://github.com/replynodes/replynodes-mcp", "source": "github" @@ -17,7 +17,7 @@ }, "environmentVariables": [ { - "description": "ReplyNodes credential claimed through https://replynodes.com/auth.md", + "description": "ReplyNodes API key (rn_test_* or rn_live_*) for headless/manual stdio use. Organization authority is resolved from the key; do not provide an organization id.", "isRequired": true, "format": "string", "isSecret": true, diff --git a/smithery.yaml b/smithery.yaml index d8e6cda..212d175 100644 --- a/smithery.yaml +++ b/smithery.yaml @@ -7,6 +7,6 @@ startCommand: properties: apiKey: type: string - description: Your ReplyNodes credential (claim it at https://replynodes.com/auth.md) + description: Your ReplyNodes API key (rn_test_* or rn_live_*) for headless/manual use. Organization authority is resolved from the key. commandFunction: | config => ({ command: 'npx', args: ['-y', '@replynodes/mcp'], env: { REPLYNODES_API_KEY: config.apiKey } })