Get started
Authentication
Every request to the Refine MCP server is authenticated with a personal API key sent as a bearer token. Each key is tied to a single brand, 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
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. No tool takes a brand as input. To work with several brands, create one key per brand.
Access is checked again on every call, not only when the key is created. A teammate invited to a brand can create their own key for it; if they are later removed from the brand, their keys stop working on the next request, with no separate revocation needed.
- 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 subscription, and the plan that counts is the brand owner’s. A teammate working on a paying brand gets the owner’s plan through their own key; there is no separate “API plan”. Creating a key requires an active plan, since a key without one could not call anything.
| Plan | Unlocks |
|---|---|
| Visibility | Analytics, opportunities and citations, Search Console and Analytics data, prompts (up to 50), tags and competitors. |
| Autopilot | Everything in Visibility, up to 200 prompts, plus content generation (30 items per type per month) and publishing. |
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.
Most people never need this: Settings → API keys does all three operations. The endpoint is there for scripts run by a signed-in user.
Create a key
curl -X POST https://app.refine-app.com/api/mcp/keys \
-H "Content-Type: application/json" \
-H "Cookie: <your dashboard session cookie>" \
-d '{ "name": "Cursor", "brand_id": "<brand-uuid>" }'Body fields are optional: name labels the key, brand_id picks the brand (default: your current brand, also settable with an x-brand-id header). Answers 201 with { key, plaintext, brand_name }; the plaintext appears in this response only.
| Status | Meaning |
|---|---|
| 401 | Not signed in. |
| 403 | The brand’s owner has no active plan, or you have no access to that brand. |
| 429 | You already hold 20 active keys. Revoke one first. |
List your keys
curl https://app.refine-app.com/api/mcp/keys \
-H "Cookie: <your dashboard session cookie>"Returns { keys: [...] }, newest first, each with id, name, key_prefix, brand_id, created_at, last_used_at and revoked_at — never the plaintext. Revoked keys stay in the list so the history survives.
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>"Answers { success: true }, or 404 when the key does not exist, is not yours, or was already revoked.
Rotate regularly
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. The server is stateless: each request stands alone, so no session needs to be kept open and no streaming notifications are sent.