clariBI Now Runs as an MCP Server: Sign Up, Upload Data, and Run Analyses From Claude Desktop or Cursor

clariBI ships an outbound Model Context Protocol server at https://claribi.com/mcp/v1/. External LLM clients (Claude Desktop, Cursor, ChatGPT custom GPTs, generic MCP-aware agents) can now do the entire onboarding loop without opening a browser: create a workspace, upload data, connect cloud sources via OAuth, ask natural-language questions, generate reports, and check usage. The launch also includes published Python and TypeScript SDKs.

If you have ever wanted to ask Claude "what does this CSV say about last quarter's revenue?" and have the answer come back as a real chart with a follow-up trail, this is the integration that makes that work end to end on clariBI.

Why this is a separate surface from the REST API

clariBI already exposes a REST API at /api/v1/ for programmatic access to dashboards, reports, data sources, and usage. The MCP Server is not a replacement. It is a parallel surface shaped for how LLM clients actually interact with external systems.

Two practical differences:

The REST API gives you a finite, hand-curated set of endpoints with predictable HTTP semantics. You pick the verb, build the payload, parse the JSON response. It is the right tool when a backend service you control wants to read or write clariBI state.

The MCP Server publishes a tool catalog the LLM can introspect and call directly. The model decides which tool fits the user's question. There is no fixed integration script. A user asks a question, the model picks list_data_sources, then maybe run_analysis, then summarises. The shape of the integration emerges per conversation.

We mention this because the two surfaces actually share the same backing data and the same authentication patterns, but the ergonomics for an LLM agent versus a backend script are different enough that mixing them produces worse outcomes than picking the right one.

What you can do from chat

The MCP Server publishes 19 tools, 3 resource schemes, and 2 prompt templates. The unauthenticated tools handle signup; the authenticated tools handle every analytics action you would otherwise do through the web app.

Sign up from inside the LLM

Two unauthenticated tools handle account creation:

register_account(email, organization_name, accept_terms=true) takes your work email and an organization name. clariBI emails a 6-digit verification code and returns a pending_id.

verify_email(pending_id, code, password) finishes signup, mints a long-lived API key for the LLM client to store, returns an access token for the current conversation, and lands you on the 14-day Trial.

No browser, no clipboard hop. The cap is one signup per email address per hour, and 5 incorrect verification attempts lock the pending row so brute force is not viable.

Bring data in

Three data ingestion tools cover the realistic shapes:

upload_data_source(name, format, data_base64) takes a base64 file inline. The cap is 25 MB encoded, around 18 MB raw. Formats supported: CSV, TSV, JSON, Excel, plain text, PDF.

ingest_url_data_source(name, url) fetches a public http(s) URL server-side, up to 100 MB. The fetcher rejects private network ranges, link-local addresses, cloud metadata endpoints (including 169.254.169.254), and URLs with embedded credentials. Redirects are validated at each hop.

request_oauth_integration_url(provider, integration_type) opens the existing clariBI OAuth flow for Google Ads, Google Analytics 4, Search Console, Google Sheets, Google Drive, BigQuery, Meta Ads, Jira, and Confluence. The LLM hands the user a browser URL; once the user clicks Allow, check_integration_status(handoff_id) flips from pending to connected and surfaces the resulting data source ID.

Database connections are deliberately not exposed as a tool. Pasting a PostgreSQL connection string into chat would leak the credential into the LLM transcript and any downstream logging. Connect databases from the web app.

Run analyses and generate reports

run_analysis(question, wait_seconds) runs a natural-language analytics question against connected data sources. It consumes AI credits (Trial includes 50), uses the same conversational engine that powers the web chat, and returns a structured payload with the headline metric, supporting chart data, follow-up questions, and the tool trace the planner used to arrive at the answer.

generate_report(title, output_format) queues report generation. get_report(report_id) polls completion and surfaces the download URL.

For billing, get_usage returns credit balances and quota headroom; get_billing_status reports the tier and renewal date; create_checkout_session returns a Stripe Checkout URL for an in-browser upgrade.

Authentication: OAuth 2.1 with DCR, plus API keys

The MCP Server supports two credential types.

For shared workspaces or multi-user installations, the cleanest shape is OAuth 2.1 with Dynamic Client Registration (RFC 7591). Spec-compliant MCP clients can register themselves without prior authentication, then walk each user through the consent screen on first use. Public clients use PKCE with SHA-256 challenges. Confidential clients receive a client secret on registration. The discovery endpoints at /mcp/v1/.well-known/oauth-authorization-server (RFC 8414) and /mcp/v1/.well-known/oauth-protected-resource (RFC 9728) advertise the supported scopes, grant types, and endpoints.

For single-user installations, paste an API key. Mint one in Settings > Developer > MCP Server in the clariBI web app. The key starts with claribi_mcp_ and is shown once. Add it to your client's MCP server config under Authorization: Bearer <key>.

Scopes mirror the REST API viewset boundaries: dashboards:read, dashboards:write, reports:read, reports:write, data-sources:read, data-sources:write, analysis:run, usage:read, billing:read, billing:write, account:write.

Tokens are stored as SHA-256 hashes; we never persist raw secrets. The claribi_mcp_* API-key authenticator at the REST API layer explicitly rejects MCP keys with a directional error, so a leaked MCP key cannot be silently reused as a REST credential.

Tier gating

A new mcp_server_access feature flag in the pricing config controls eligibility. MCP access ships with Trial, Starter, Professional, and Enterprise. It is excluded from Free and Lite. The signup tools (register_account, verify_email, check_pricing) work without a subscription so the chicken-and-egg of "you cannot use this until you have an account" is avoided.

Per-tier data caps apply to the upload tools the same way they apply to the web upload path. Trial allows 3 data sources, 5 file uploads per month, and 1 GB of storage; the paid tiers scale up. Tool error responses tell you which quota was hit so the LLM can explain it back to the user.

Two SDKs, codegen-driven from the live catalog

Both SDKs ship with typed method surfaces produced at build time from the live tool catalog at /api/mcp-server/tool-catalog/. The codegen runs in CI before each release, so the typed method list in the published package cannot drift from the server.

Python:

pip install claribi-mcp

from claribi_mcp import Client

with Client(api_key="claribi_mcp_...") as client:
    client.initialize()
    sources = client.list_data_sources()
    result = client.run_analysis(
        question="What was revenue by region last quarter?",
        wait_seconds=30,
    )
    print(result.text)

TypeScript:

npm install @claribicom/mcp

import { Client } from '@claribicom/mcp';

const client = new Client({ apiKey: 'claribi_mcp_...' });
await client.initialize();
const r = await client.callTool('run_analysis', {
  question: 'What was revenue by region last quarter?',
  wait_seconds: 30,
});
console.log(r.text());

Sources, license, version policy, and a quickstart for the OAuth bearer path are in the SDK docs. Both packages are published under the MIT license.

A realistic end-to-end session

A user opens Claude Desktop with the clariBI MCP Server configured under their mcpServers block. The conversation goes like this.

User: "Can you create me a clariBI account?"

Claude: Calls register_account with the user's email and an organization name. clariBI emails a 6-digit code. Claude asks the user to paste it.

User pastes the code; Claude asks for a password.

Claude: Calls verify_email. clariBI returns an access token, a long-lived API key, and a Trial workspace. Claude stores the key in its MCP server config and confirms.

User: "Here's a CSV of last quarter's sales (drags file in)."

Claude: Reads the file, base64-encodes it, calls upload_data_source(name="Q3 sales", format="csv", ...) with wait_seconds=30 so preprocessing finishes before the next call.

User: "What was total revenue by region?"

Claude: Calls run_analysis(question="What was total revenue by region?", wait_seconds=30). The conversational engine picks top_n(metric=revenue, dimension=region) from the planner, returns a chart payload, and Claude renders the headline and the bar chart inline.

User: "Can you also connect our Google Ads data so we can layer in CPA?"

Claude: Calls request_oauth_integration_url(provider="google", integration_type="google_ads"). The user opens the URL in a browser, clicks Allow. Claude polls check_integration_status until it flips to connected, then runs a follow-up run_analysis.

That entire flow happens without leaving the LLM client. Credentials never traverse the chat: passwords go through the verify step, OAuth credentials stay in the browser, file content is in transit only during the upload call.

Why we built this now

Two things made this the right time. First, the MCP spec stabilised at version 2025-03-26 with streamable HTTP as the primary transport. Second, every major LLM client now has first-party MCP support: Claude Desktop ships it, Cursor's implementation handles OAuth end to end, and ChatGPT custom GPTs can wire it through the actions surface.

Building the integration on the protocol rather than per-client glue means there is one server to maintain and every spec-compliant client picks it up. That is a different shape from where integrations sat 12 months ago, and we expect more BI work to live in chat surfaces going forward.

What's next

A few items are deliberately on the roadmap but not in this release. Database connection via MCP stays deferred because credentials in chat is a security regression we are not willing to normalize yet. Chunked upload for files larger than 25 MB is on the list for v2 once a customer hits the cap. Inline tabular data (passing rows directly) stays out for now because asking the LLM to produce a CSV and base64 it works fine and avoids a parallel code path.

If you are wiring this into Claude Desktop or Cursor today, start with the MCP overview and the Claude Desktop setup guide. If you would prefer the REST API or are building from a backend service you control, the API reference covers the equivalent surface. If you want the typed clients, pip install claribi-mcp and npm install @claribicom/mcp are already on PyPI and npm.

Trial workspaces include 50 AI credits and ship with MCP Server access from day one. The signup tools above will get you there without leaving chat.