MCP tokens & scopes

An MCP token is the credential an AI client authenticates with. Create and manage them under Account settings → MCP Access.

A token acts as you

This is the single most important thing to understand. A token carries your identity, not a set of permissions of its own:

• It can reach every site you can reach — through direct ownership, your organization, an agency you belong to, or a team a site is shared with.
• It can never reach more than you can. If you lose access to a site, every token you hold loses it at the same moment.
• It is checked on every single call, not once at creation.

So a token is a way to narrow your access for an agent, never to widen it — and sharing one with a colleague hands them your access, which is why you should not.

Creating a token

1. Name it after the client that will hold it — "Claude Desktop", "CI reporting agent". This is how you tell them apart later when deciding what to revoke.
2. Choose the access level (below).
3. Restrict it to specific sites, if you want. The default is every site you can reach.
4. Set an expiry — never, 30 days, 90 days or a year. A token for a one-off analysis should not outlive it.

Access levels

• Read only — the agent can look at everything and change nothing. Start here. It is enough for every reporting, investigation and "why did this happen?" question.
• Read & write — the agent can also create and change funnels, experiments, surveys, opt-in forms, feature flags, heatmaps and custom events, and change a site’s collection settings. Be deliberate: starting an A/B test, publishing an opt-in form or pausing tracking takes effect for live visitors.
• Custom — pick read and write per area. Use it to grant, say, write access to funnels while keeping experiments read-only, or to grant every write except the site settings that control what is collected.

The AI scope is separate

ai:invoke lets the agent use Spectry’s own AI features — Ask-AI, insight generation and survey theme analysis. It is not included in "Read & write" because those calls are billed per use. Grant it explicitly under Custom if you want it.

Copy the token immediately

The token is shown once, right after you create it. Spectry stores only a SHA-256 hash of it, so it genuinely cannot be shown again — not by you, not by support. If you lose it, revoke that token and create another.

The same dialog gives you a ready-made Claude Desktop config block with the token already in it.

Keeping a token safe

• Never put it in a URL. Spectry refuses any request with a token in the query string and tells you to revoke it — by that point it is already in access logs, proxy logs and possibly a Referer header.
• Never commit it to a repository or paste it into a shared document.
• One token per client. Separate tokens mean you can revoke the one that leaked without breaking everything else.
• Check Last used before revoking — it tells you whether anything still depends on that token.

Revoking

Revoke from the token list. It stops working within a minute, and any client holding it loses access immediately afterwards. Revocation cannot be undone — create a new token instead.

Revoked tokens stay in the list rather than disappearing, so Last used remains available as evidence of what a compromised credential reached.

Other Spectry keys are not interchangeable

Spectry issues three kinds of credential, and each opens exactly one door:

• mcp_… — an MCP token. Only authenticates the MCP endpoint.
• sk_… — a server SDK secret key, scoped to one site.
• wk_… — the write key, which is published in your page source and authenticates nothing on its own.

Presenting the wrong one gets a clear error naming the mistake rather than a generic failure.

Limits

• 25 active tokens per user. Revoke one before creating another if you hit it.
• 240 requests per minute per token — comfortably above what an agent’s tool loop needs, and enough to stop a runaway loop.

See Connect AI to Spectry (MCP) for wiring a client up and what the agent can actually do.