> ## Documentation Index
> Fetch the complete documentation index at: https://rankahead.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
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.
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.
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
```bash curl theme={null}
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:
```json mcp.json theme={null}
{
"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.
```json theme={null}
{
"jsonrpc": "2.0",
"id": null,
"error": {
"code": -32000,
"message": "Missing Authorization: Bearer "
}
}
```
**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.
```json theme={null}
{
"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 ` | 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
Understand the endpoint, protocol details, and available tools.
Browse per-tool documentation with input schemas and response examples.