MCP server

Ray9 ships a first-party MCP server so any MCP-aware client — Claude Desktop, Cursor, VS Code (via Continue / Cline), Windsurf, Goose, your own agent runtime — can call SEO data as native tools. The server is hosted by Ray9, not something you run locally. Identity, billing, and rate limits flow through the same chain as direct REST calls.

Endpoint

https://api.ray9.ai/mcp

The transport is the streamable-HTTP MCP spec — POST /mcp for tool invocations, GET /mcp for resumable SSE streams, DELETE /mcp for explicit session termination.

Authentication

Send your Ray9 API key as a Bearer token on every request:

Authorization: Bearer rk_…

The key issuance, prefix, rotation, and revocation rules are the same as REST — see Authentication. The server identifies itself as "ray9" in the MCP serverInfo response.

Connecting your client

Different MCP clients use different config surfaces for remote (streamable-HTTP) servers. The shared shape is: a server name, the URL, and the Authorization header.

The MCP client ecosystem is still settling on streamable-HTTP config schemas (the spec only stabilised mid-2025). The examples below match each client's documented shape at the time of writing — if your client rejects the config silently, check its release notes for schema changes and fall back to the Stdio shim.

Claude Desktop

Claude Desktop adds remote MCP servers through Custom Connectors in the claude.ai UI, not via claude_desktop_config.json (which today only configures stdio MCP servers).

1. Open claude.ai → Settings → Connectors → Add custom connector.
2. Paste https://api.ray9.ai/mcp as the server URL.
3. When prompted for authentication, supply your Ray9 API key as a Bearer token.

If your Claude build doesn't yet expose Custom Connectors, use the mcp-remote stdio bridge in claude_desktop_config.json until our own Stdio shim ships:

{
  "mcpServers": {
    "ray9": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.ray9.ai/mcp",
        "--header",
        "Authorization:Bearer rk_…"
      ]
    }
  }
}

Quit and relaunch Claude Desktop fully (not just close the window) for the new server to register.

Cursor

Add to ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (per-project):

{
  "mcpServers": {
    "ray9": {
      "url": "https://api.ray9.ai/mcp",
      "headers": {
        "Authorization": "Bearer rk_…"
      }
    }
  }
}

Re-open the Cursor command palette → MCP to verify the server is live.

Goose

goose configure

Pick Add Extension → Remote Extension (Streamable HTTP) and paste https://api.ray9.ai/mcp as the URL. Goose's CLI flow will prompt for any custom headers — supply Authorization: Bearer rk_….

Header support in Goose's streamable-HTTP extensions isn't yet documented in their public docs. If the prompt for headers doesn't appear in your version, fall back to the Stdio shim.

VS Code

VS Code's first-party MCP support reads .vscode/mcp.json (workspace) or your user mcp.json:

{
  "servers": {
    "ray9": {
      "url": "https://api.ray9.ai/mcp",
      "headers": { "Authorization": "Bearer rk_…" }
    }
  }
}

Reload the window after editing.

Third-party VS Code extensions (Continue, Cline, Roo Code) each have their own MCP config surface — consult the extension's docs for the exact JSON. The values to supply are always:

• URL — https://api.ray9.ai/mcp
• Transport — streamable HTTP
• Header — Authorization: Bearer rk_…

Other clients

Any client that implements MCP's streamable-HTTP transport can connect with the URL + auth header above. If yours only supports stdio MCP, see Stdio shim below.

Tool catalog

The server currently exposes two tools:

Tool descriptions and input schemas are returned by tools/list so your LLM client can introspect them — you don't need to memorise input shapes.

When a tool fails, Ray9 returns a structured error message in the CallToolResult.content[] array (text content describing the error code and request id), and isError: true so the LLM knows the call failed. Codes match the REST error reference.

Sessions and resumability

The streamable-HTTP transport supports resumable sessions: if the GET-side SSE connection drops, your client can reconnect with the same mcp-session-id header and pick up from the last event id without losing in-flight tool calls. Ray9 backs this with Redis using a 30-minute sliding TTL (refreshed on every event), plus an in-process idle-session sweeper that closes sessions after 30 minutes of inactivity.

Most client libraries handle reconnect transparently — you don't need to implement it yourself. If you go silent for 30+ minutes, expect to start a new session on your next call.

Rate limits

MCP traffic counts against the same per-org rate limit as REST — see Rate limits. The MCP layer adds no additional throttle; if you've already hit 60 requests in the current 60-second window via REST, an MCP tools/call will return a structured rate-limit error.

Stdio shim

If your client only supports stdio MCP (e.g. older versions of Claude Desktop without HTTP MCP support), upgrade to a version that supports streamable-HTTP MCP, or run a generic stdio↔HTTP MCP bridge against https://api.ray9.ai/mcp.

Troubleshooting

• Tools don't appear after editing config. Quit and restart the client fully (not just close the window). Some clients also need to be re-launched from the dock / start menu.
• unauthenticated error on every call. Verify the Authorization header is Bearer rk_… exactly (single space, correct prefix, key not revoked in Settings → API keys).
• Connection refused. Confirm the URL is https://api.ray9.ai/mcp (no trailing slash, no /v1 prefix). The MCP endpoint is at the root of the API host.
• rate_limited error suddenly. You've shared the per-org bucket with another client (CLI, REST, web). See Rate limits.

For deeper symptom-driven recipes, see Troubleshooting.