Authentication
MCP token scopes, rate limits, usage metering, and key management
Two ways to authenticate
- OAuth custom connector — for Claude Desktop and Claude.ai. One-click sign-in, no token to manage. See Connect to Claude.
- 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 | Write-back operations (Meta CAPI conversion export) |
Default scope when creating a token: mcp:read.
Write scope
mcp:write allows sending conversion data to external platforms. Only grant this when you specifically need Meta CAPI write-back. The workspace admin must also enable write-back in workspace settings.
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, compare_forecast_scenarios | 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, forecasting, 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.