Authentication
Every request to the Refine MCP server is authenticated with a personal API key sent as a bearer token. Keys are tied to a single brand and a single subscription, so a client only ever sees the data it’s meant to.
API keys#
A Refine key looks like this:
rfn_live_abc1xyz… (rfn_live_ + 43 random characters)Send it on every request as the Authorization header:
Authorization: Bearer rfn_live_abc1xyz…Treat keys like passwords
The full key is shown only once, at creation. Refine stores only a SHA-256 hash — we can never show it to you again. If you lose it, revoke it and create a new one. Anyone with the key can act on your brand within the limits of the attached plan.How keys are stored
Refine persists only the hash of your key plus a short display prefix (e.g. rfn_live_abc1) so you can recognise it in a list. The 32 bytes of entropy in each key mean there’s nothing practical to brute-force, and the deterministic hash keeps lookups fast on every request.
Scoping & isolation#
Each key is bound to exactly one brand at creation time. That binding is frozen — a key can never be pointed at a different brand, and tool calls are always filtered to the key’s brand server-side. To work with several brands, create one key per brand.
1 key
maps to exactly 1 brand
1 brand
can have many keys
20 keys
max active per account
Plan gating#
Tools are gated by your subscription. A key inherits whatever plan the account holds — there’s no separate “API plan”.
| Plan | Unlocks |
|---|---|
| Visibility | Analytics, prompts, tags and competitors (read & write). |
| Autopilot | Everything in Visibility, plus content generation. |
If you call a tool your plan doesn’t cover, the server returns a clear error telling you which plan is required. Manage your plan from the subscriptions page.
Managing keys#
Keys are managed through the keys endpoint while signed in to your dashboard. The session cookie identifies you; the endpoint never accepts a bearer key to manage other keys.
List your keys
curl https://app.refine-app.com/api/mcp/keys \
-H "Cookie: <your dashboard session cookie>"Returns each key’s id, name, prefix, creation date and last_used_at — never the plaintext.
Revoke a key
Revoking is immediate and permanent. Any client using that key starts getting 401 on its next request.
curl -X DELETE https://app.refine-app.com/api/mcp/keys/<key-id> \
-H "Cookie: <your dashboard session cookie>"Rotate regularly
Use a distinct key per client (one for Claude Desktop, one for Cursor, one for a script). If one leaks or a teammate leaves, revoke just that key without disrupting the others.The endpoint#
All tool traffic goes to a single Streamable HTTP endpoint, over POST (and GET for the stream):
https://app.refine-app.com/api/mcp/mcpUnauthenticated requests are rejected with 401 before any tool runs.