MCP Authentication — API Tokens & Security

Create and manage MCP tokens for Rankahead’s Model Context Protocol server. Learn how to authenticate requests and follow security best practices.

Every request to the Rankahead MCP server requires a valid API token. Tokens are scoped to your organisation, so all tools you call operate on your organisation’s data. You create and manage tokens directly in the Rankahead app — no separate developer console is required.

Creating a token

1. Open your MCP settings

   Go to Settings > MCP in the Rankahead app. You’ll see a list of any existing tokens alongside an option to create a new one.

2. Create a new token

   Click Create token and give it a descriptive name — for example, cursor-agent or automation-prod. A clear name makes it easy to identify which client is using which token and to revoke the right one if needed.

3. Copy the token

   The full token value is shown once, immediately after creation. Copy it now and store it somewhere secure such as a password manager or secrets manager. You will not be able to view it again after you leave this screen.

The token is only shown in full at creation time. If you lose it, you must revoke the old token and create a new one.

Using the token

Include your token in the Authorization header of every request to the MCP endpoint. Use the Bearer scheme:

Authorization: Bearer YOUR_MCP_TOKEN

All requests go to:

POST https://app.rankahead.ai/api/mcp

Complete curl example

curl

curl -s -X POST https://app.rankahead.ai/api/mcp \
  -H "Authorization: Bearer YOUR_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_dashboard",
      "arguments": {}
    }
  }'

Replace YOUR_MCP_TOKEN with the token value you copied from Settings > MCP.

Configuring an MCP client

Most MCP clients let you supply environment variables or a configuration file to set the server URL and authorization header. The example below shows a typical mcp.json configuration:

mcp.json

{
  "mcpServers": {
    "rankahead": {
      "url": "https://app.rankahead.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

Store the token in an environment variable (for example, RANKAHEAD_MCP_TOKEN) and reference it in your config file rather than hardcoding the value. This keeps the secret out of version control.

Error codes

The server returns standard JSON-RPC error responses when authentication fails. Both errors use HTTP status 401 and JSON-RPC error code -32000.

Missing authorization header

Returned when the request does not include an Authorization header at all, or the header is present but empty.

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32000,
    "message": "Missing Authorization: Bearer <token>"
  }
}

Fix: Add the Authorization: Bearer YOUR_MCP_TOKEN header to your request.

Invalid or revoked token

Returned when the token is present but does not match any active token in your organisation — either it was never valid, or it has been revoked.

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32000,
    "message": "Invalid or revoked MCP token"
  }
}

Fix: Verify the token value is copied correctly without leading or trailing whitespace. If the token was revoked, create a new one in Settings > MCP.

Error reference

HTTP status	JSON-RPC code	Message	Cause
401	-32000	Missing Authorization: Bearer <token>	No Authorization header on the request.
401	-32000	Invalid or revoked MCP token	Token does not exist or has been revoked.

Revoking a token

To revoke a token, go to Settings > MCP in the Rankahead app, find the token by name, and click Delete. The token is invalidated immediately — any subsequent request using it returns an Invalid or revoked MCP token error.

Revoking a token does not affect other tokens. If you have multiple clients configured with separate tokens, only the deleted token stops working.

Organisation scope

Tokens are tied to your organisation, not to an individual user account. Every tool call made with a token operates on your organisation’s data — domains, prompts, blog posts, GSC connections, and so on. There is no per-user token scoping at this time.

This means:

• Any token from your organisation can access all tools and all of your organisation’s data.
• Inviting a new member does not automatically give them a token — tokens are created explicitly in Settings > MCP.
• Removing a member from your organisation does not revoke tokens. Revoke tokens manually if a team member departs.

Security best practices

Treat MCP tokens like passwords. Anyone with a valid token can read and modify your organisation’s data through the MCP server.

Follow these guidelines to keep your tokens secure:

• Use one token per client. Create a separate token for each tool or agent (for example, one for Cursor and one for a CI automation). This limits the blast radius if a token is compromised and makes it easy to revoke access for a specific client without disrupting others.
• Never expose tokens in client-side code. Tokens must only be used in server-side or local environments. Do not embed them in browser JavaScript, mobile apps, or any code that runs in untrusted contexts.
• Keep tokens out of version control. Store token values in environment variables or a secrets manager, not in config files that get committed to git.
• Rotate tokens periodically. If a token may have been exposed, revoke it immediately and generate a new one. Update the new token in all affected client configurations.
• Audit your tokens regularly. Review the list of active tokens in Settings > MCP and delete any that are no longer in use.

Next steps

MCP overview

Understand the endpoint, protocol details, and available tools.

Tool reference

Browse per-tool documentation with input schemas and response examples.