Connect Rankability to AI Assistants

Step 1 — Create an API key

1. 1

   Go to Rankability → Settings → API keys.

2. 2

   Click Create API key. Give it a name (e.g., "Cursor"), select the scopes you want to grant, and copy the key.

3. 3

   The key starts with rk_live_ and is shown only once — store it securely.

Step 2 — Configure your client

{
  "mcpServers": {
    "rankability": {
      "url": "https://rankability.com/mcp",
      "headers": {
        "Authorization": "Bearer rk_live_YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "rankability": {
      "command": "npx",
      "args": ["--yes", "rankability-mcp"],
      "env": {
        "RANKABILITY_API_KEY": "rk_live_YOUR_API_KEY"
      }
    }
  }
}

Windsurf and VS Code Copilot use the same mcpServers URL + headers format as Cursor. After saving the config, restart your client and Rankability tools will appear in the available MCP tool list.

Tools not appearing

Restart your client after updating the configuration. For OAuth clients, confirm the connector status in your client's settings panel — if it shows "disconnected," re-run the consent flow. For API key clients, verify the key starts with rk_live_.

Authentication errors (401)

For OAuth: the token may have been revoked or the organization switched. Reconnect the connector. For API keys: verify you copied the full key. Keys are shown only once at creation — if lost, create a new key in Settings → API keys.

Forbidden errors (403)

The granted scopes don't include the scope required by the tool. For OAuth, revoke and re-authorize granting the missing scope. For API keys, edit the key in Settings → API keys to add the scope.

Insufficient credits (402)

The action tool requires credits and your balance is too low. Check your balance with the get_credit_balance tool or top up in Settings → Billing.

Missing data

Confirm your account has the data you're asking about — for example, get_reporter_summary returns no projects if no Reporter projects have been created in the active organization.

Rate limit errors (429)

You've exceeded 60 requests per minute. Wait one minute and retry. Persistent rate limiting may indicate a runaway loop in your assistant — review the conversation and consider whether the assistant is making redundant calls.