Authentication
MCP token scopes, rate limits, usage metering, and key management
Two ways to authenticate
- OAuth custom connector — for Claude.ai, Claude Desktop, Claude Code, Cursor and ChatGPT. One-click sign-in, no token to manage. See Connect an AI client.
- Personal access token — for Claude Code, Cursor, scripts, and CI. Covered on this page.
Both produce a short Bearer token the MCP server validates; the difference is whether you manage it (token) or Claude does (connector). Connector access tokens are short-lived — they expire after 1 hour and Claude refreshes them automatically with a 60-day refresh token.
All MCP requests carry a Bearer token in the Authorization header — created by you as a personal access token, or issued automatically by the OAuth connector flow.
Authorization: Bearer atb_user_your_token_hereMCP tokens are user-scoped -- a single token grants access to every workspace you belong to. The workspace and profile are specified per tool call, not stored on the token.
Creating a token
Create tokens from Developer > MCP Tokens in the Atribu dashboard. You can have up to 10 active tokens per user — revoke unused ones to free a slot.
Show once
Tokens are shown exactly once at creation. Store them securely -- you cannot retrieve them later.
Scopes
Each token has granular scopes that control what data and actions are available.
| Scope | Access |
|---|---|
mcp:read | Attribution data, campaigns, creatives, journeys (PII masked) |
mcp:read_pii | Unmask email, phone, and full name when include_sensitive=true |
mcp:write | Every write: create workspaces and profiles, mint tracking keys, start connect hand-offs, define conversions, configure Conversion Sync, and export conversions to Meta CAPI |
Default scope when creating a token: mcp:read.
Write scope
mcp:write lets an agent configure your attribution AND send conversion data to external platforms — since #1058 it maps to exports:read + exports:write as well as the attribution-write set, because configuring a CAPI destination is what the onboarding tools do. Two things still gate it beyond the grant: a workspace admin must enable write-back in workspace settings, and the caller must hold an owner/admin role. Reads and every write tool's preview mode work without any of it.
Rate limits
MCP uses weighted rate limiting. Each tool has a cost in units, and your token has a per-minute burst cap.
Per-minute cap: 120 units (default).
| Tool | Cost |
|---|---|
whoami, list_workspaces, list_profiles | 0 units (free) |
explain_campaign, explain_customer_journey, creative_fatigue_check, find_anomalies, whatsapp_attribution_summary | 2 units |
compare_attribution_models | 5 units |
send_meta_conversions, apply_recommendation | 10 units |
| Every other tool (performance, campaign, traffic, engagement, list, workspace creative-intelligence, and recommendation reads) | 1 unit |
When rate limited, the tool returns a rate_limited error with retry_after (seconds) and retryable: true.
Usage metering
Your subscription includes a monthly unit allowance. Units are committed when the call is admitted — before the tool runs — so a call that fails mid-execution still counts against your period allowance.
| Plan | Units per period |
|---|---|
| Trial | 2,000 / 14 days |
| Starter | 20,000 / month |
| Growth | 200,000 / month |
| Agency | 2,000,000 / month |
| Enterprise | Unlimited |
Check your current usage from the Developer > MCP Tokens tab in the dashboard.
Token management
Rotation
Rotate tokens with zero downtime:
Click Rotate next to the token in the dashboard
A new token is generated and revealed once
Update your AI tool configuration with the new token
The old token keeps working for a 48-hour grace period, then is retired automatically
Revocation
Click Revoke to immediately invalidate a token. Any AI tool using that token will lose access instantly.
Concurrent sessions
Tokens have no server-side state. Multiple AI tools or IDE sessions can use the same token simultaneously without interfering with each other. Each tool call specifies its own workspace and profile scope.
Related
Connect to Claude
Add Atribu as a native connector in Claude Desktop or Claude.ai with one-click OAuth — no token to copy or paste
Available Tools
52 MCP tools: the onboarding golden path (provision, tracking install, connect hand-offs, conversion definitions, Meta CAPI setup), performance summaries, funnel analysis, traffic breakdowns, campaign drill-downs, customer journeys, workspace creative intelligence, recommendations, and Meta CAPI write-back