MCP authentication

The MCP server accepts two kinds of credential: an OAuth 2.1 access token, obtained through dynamic client registration, or a claribi_mcp_ API key. Both are sent as Authorization: Bearer ... on every request.

OAuth or API key

Both need an organization on Trial, Starter, Professional or Enterprise with an active subscription.

API keys

Mint a key

1. Sign in and open Settings > Developer, section MCP Server (LLM clients).
2. Enter a name, for example "Claude Desktop", and click Mint MCP API key.
3. Copy the key. It starts with claribi_mcp_ and is shown once; clariBI keeps only a hash.

Use it

For a client that takes a URL and headers:

{
  "mcpServers": {
    "claribi": {
      "url": "https://claribi.com/mcp/v1/",
      "headers": { "Authorization": "Bearer claribi_mcp_..." }
    }
  }
}

Client-specific steps: Claude Desktop, Cursor. Behind the scenes clariBI exchanges the key for a short-lived internal token (15 minutes) and records calls against that token.

MCP keys only work with the MCP server; the REST API rejects them and uses its own keys.

Revoke it

Click Revoke next to the key in Settings > Developer. The next request with that key fails.

OAuth 2.1 with dynamic client registration

Clients discover the endpoints from the metadata documents:

The metadata documents are also served under /mcp/v1/.well-known/.

Register a client

POST /mcp/v1/oauth/register
Content-Type: application/json

{
  "client_name": "My agent",
  "redirect_uris": ["https://agent.example.com/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "dashboards:read reports:read analysis:run"
}

The response contains a client_id (prefix claribi_mcp_cli_). A confidential client (any token_endpoint_auth_method other than none) also gets a client_secret, shown only in this response.

Authorization code flow

1. Create a PKCE verifier and an S256 challenge. PKCE is required for public clients and only S256 is accepted.
2. Send the user to /mcp/v1/oauth/authorize with response_type=code, client_id, redirect_uri, scope, state, code_challenge and code_challenge_method=S256.
3. The user signs in to clariBI if needed, reviews the requested permissions and approves.
4. clariBI redirects to redirect_uri with code and your state. The code is single-use and valid for 60 seconds.
5. Exchange it at /mcp/v1/oauth/token:

POST /mcp/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...&redirect_uri=https://agent.example.com/oauth/callback
&client_id=claribi_mcp_cli_...&code_verifier=...

{
  "access_token": "claribi_mcp_tok_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "scope": "dashboards:read reports:read analysis:run"
}

Refresh and revoke

Refresh with grant_type=refresh_token, your refresh_token and client_id. Each refresh revokes the old token and returns a new pair; refresh tokens expire after 30 days. To revoke, post a token to /mcp/v1/oauth/revoke, or revoke the token or the whole client in the Developer Portal's MCP tab.

Scopes

Keys minted in Settings, and the key returned by signup from an assistant, get this default set: dashboards:read reports:read data-sources:read data-sources:write usage:read analysis:run forecasts:read. For other permissions (generating reports, creating or running forecasts, billing) connect with OAuth and grant them on the consent screen.

Rate limits

Over the limit, the server answers with HTTP 429 and JSON-RPC error -32003.

Security notes

• Keys, access tokens and client secrets are stored as SHA-256 hashes.
• redirect_uri must match a registered URI exactly.
• The organization's subscription is checked on every request: suspended or cancelled organizations are refused.
• If the person who minted a key is deactivated or leaves the organization, the key stops working.

Related

• Tool reference
• Sign up from an assistant
• SDKs