Authentication

The MCP server accepts two credential types: an OAuth 2.1 bearer token issued via Dynamic Client Registration, and a static claribi_mcp_* API key. Both end up as an Authorization: Bearer <value> header on every JSON-RPC request.

Choosing between OAuth and API keys

API key flow

1. Mint a key

1. Sign in at claribi.com/app/login.
2. Go to Settings > Developer > MCP Server (or the full Developer Portal).
3. Type a name (for example, "Claude Desktop") and click Mint MCP API key.
4. Copy the key. It starts with claribi_mcp_ and is shown only once.

2. Use the key

Add the key to your client's MCP server config as a bearer token:

Authorization: Bearer claribi_mcp_<your-key-suffix>

For Claude Desktop, the config snippet looks like this:

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

3. Revoke a key

Revocation is immediate. Open Settings > Developer > MCP Server, find the key in the list, and click Revoke. Any client using the key receives a 401 on the next request.

OAuth 2.1 with Dynamic Client Registration

Spec-compliant MCP clients can discover everything they need from these endpoints:

Registration request

Register a new client by POSTing to /mcp/v1/oauth/register. PKCE with S256 is required for public clients (no client secret).

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

{
  "client_name": "My LLM Agent",
  "redirect_uris": ["https://my-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 and, for confidential clients, a single-use client_secret:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "client_id": "claribi_mcp_cli_abc123",
  "client_id_issued_at": 1717200000,
  "client_name": "My LLM Agent",
  "redirect_uris": ["https://my-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"
}

Authorization code flow

1. Generate a PKCE verifier and challenge (S256).
2. Redirect 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 logs in (if not already), reviews the scope list, and clicks Allow.
4. clariBI redirects back to redirect_uri with code and the original state.
5. Exchange the code at /mcp/v1/oauth/token with grant_type=authorization_code, the code, redirect_uri, and code_verifier.

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

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

The response contains the access token (and a refresh token if requested):

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

Refresh

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

grant_type=refresh_token
&refresh_token=claribi_mcp_rft_...
&client_id=claribi_mcp_cli_abc123

The old token is revoked when a new pair is issued. Refresh tokens expire after 30 days.

Revocation

Pass any access or refresh token to /mcp/v1/oauth/revoke per RFC 7009. The owning user can also revoke from Settings > Developer > MCP Server.

Scopes

Default scopes for API keys minted without an explicit scope list: dashboards:read reports:read data-sources:read usage:read analysis:run.

Rate limits

Exceeding a limit returns a JSON-RPC error with code: -32003 and HTTP 429.

Security notes

• API keys and access tokens are stored as SHA-256 hashes. The raw value is shown once and never again.
• redirect_uri is matched exactly (RFC 8252). Prefix and wildcard matching are not supported.
• Public clients must use PKCE with S256. Plain code challenges are rejected.
• Org subscription status is checked on every request. Suspended or cancelled orgs cannot use the MCP server even if a token is still active.
• The creator of an API key must still be an active member of the org. Offboarding a user blocks every key they minted.