MCP connector

Connect Claude, ChatGPT, Cursor or any MCP client to your organization's Lucen data. Your assistant can answer questions from your analytics, explain how a metric is calculated and draft dashboards for you to review.

#Overview

Lucen is a managed data pipeline. It loads your marketing and business sources into a BigQuery warehouse and models them into clean, analysis-ready tables (the gold layer). The warehouse is either your own Google Cloud project or one Blumie runs for you, where your organization has its own dataset prefix and service account. The Lucen MCP server gives an AI assistant governed access to those tables.

With the connector, your assistant can:

• Answer questions about your data by running read-only queries on your organization's warehouse, starting from your gold tables.
• Reuse the saved, validated queries in your organization's query library.
• Explain how a metric is calculated by reading your pipeline's transformation code.
• Tell you how fresh the data is, table by table.
• Draft Blocks dashboard pages for you to review and publish in the Lucen portal.

The assistant only sees what your Lucen account can see, and every query runs in your organization's warehouse.

#Requirements

• A Lucen account that belongs to at least one organization. Ask your organization owner for an invite if you don't have one.
• An AI client that supports remote MCP servers with OAuth: Claude (web, desktop or Claude Code), ChatGPT (with developer mode) or Cursor.

#Connect

Every client uses the same server URL:

The first time you connect, your browser opens Lucen to sign in and approve access. See Authentication and permissions.

Menu names can differ slightly between client versions and languages.

#Claude (web or desktop)

1. 1Open Settings → Connectors → Add custom connector.
2. 2Paste the server URL and save.
3. 3Approve access when your browser opens.

#ChatGPT

1. 1In ChatGPT on the web, open Settings → Apps → Advanced settings and turn on Developer mode. On Business and Enterprise workspaces, an admin may need to allow it first under Workspace settings → Permissions & Roles → Connected Data.
2. 2Open Settings → Connectors → Add custom connector and paste the server URL.
3. 3Approve access when your browser opens.

Developer mode is available on ChatGPT Plus, Pro, Business, Enterprise and Education plans.

#Cursor

Add this to .cursor/mcp.json, then approve access when your browser opens:

{
  "mcpServers": {
    "lucen": {
      "url": "https://lucen-api.blumie.io/mcp"
    }
  }
}

#Claude Code

Run this in your terminal:

$claude mcp add --transport http lucen https://lucen-api.blumie.io/mcp

Then run /mcp inside Claude Code, pick lucen, choose Authenticate and approve access when your browser opens.

#Optional: skills for developers

The connector works on its own. Developers who use Claude Code or another client that supports skills can also install Lucen's skills, which teach the assistant your data model and the Blocks dashboard format in more depth:

$npx skills add Blumie-io/lucen-skills --skill lucen-data

$npx skills add Blumie-io/lucen-skills --skill lucen-blocks

#Authentication and permissions

Lucen uses OAuth 2.1 with PKCE. Your client registers itself automatically, and you never paste a password or API key into the AI client.

When you connect, Lucen shows a consent screen. On it you:

• Sign in with your Lucen account.
• Choose which of your organizations this connection may use. You can grant one or several.
• Review what the connection is allowed to do.

A connection can hold two permissions:

Access follows your Lucen membership on every call. If you are removed from an organization, the connection stops working for that organization right away, even if the client still holds a token.

Access tokens last 1 hour. The client renews them with a refresh token that lasts 30 days, and each renewal starts a new 30 days, so a client in regular use stays connected. A client left unused for 30 days asks you to sign in again. Token lifetime is not what ends access: membership is, as described above.

To disconnect, log out of or remove the Lucen connector in your AI client. To stop someone's access entirely, remove them from the organization in Lucen.

#Tools

The server exposes 17 tools. Every tool declares whether it only reads or also writes.

Only save_query and upsert_page write, and both need the write permission. Neither deletes data or changes anything already published: saving a query adds a new entry to your library, and a page draft stays private until someone publishes it in the Lucen portal. Clients that follow MCP tool hints, such as Claude, ask you to confirm before either one runs.

#Example prompts

Answer a question from your data

The assistant checks your query library with find_query. If a saved query fits, it runs it with run_query. Otherwise it looks up your tables with list_tables, writes a read-only query and runs it with run_bigquery.

Rank campaigns fairly

The assistant uses compare_entities, which normalizes for how long each campaign was active, so a short campaign is not ranked below a long one just for having fewer days of spend.

Build a dashboard

The assistant calls plan_page first and asks you a few questions, such as which platforms and which period. It then saves the queries it needs with save_query and writes the page with upsert_page. You get a preview link and decide whether to publish it in the Lucen portal.

#Data handling and security

• The connector does not store query results. Queries run in your organization's BigQuery warehouse and the results go back to your AI client. The MCP server does not write result rows to Lucen's database. For saved-query runs it records metadata only: the parameter values used, row count, bytes processed, duration, whether BigQuery's cache answered, and who ran it. BigQuery keeps its standard query cache, about 24 hours, in the warehouse project. Lumi, the chat inside the Lucen portal, stores its own conversations separately.
• Read-only by design. A query must be a single SELECT or WITH statement. Anything that would write, delete or change tables is refused before it reaches BigQuery.
• Scoped to your organization's warehouse. Queries run only in the warehouse of the organization the call names. On your own BigQuery, that is your Google Cloud project, and the connector can read what you granted Lucen there. On the warehouse Blumie runs, a query that references another organization's datasets is refused before it runs, and your organization's service account can only read data in its own datasets.
• Cost and size limits. Every query is checked with a BigQuery dry run first. Queries that would scan too much data are refused, and results are capped at 1,000 rows.
• Membership is checked on every call. Each call names the organization it acts on, and Lucen confirms both the connection's grant and your current membership before running it.
• Nothing is published for you. Dashboard pages written by an assistant are drafts. Publishing is always a click by a person in the Lucen portal.
• Your AI provider sees the results you ask for. Query results are sent to the AI client you connected, under your agreement with that provider.

Questions you send to find_query are matched against your query library with Google Vertex AI embeddings, which run in Google Cloud alongside the rest of Lucen.

For more detail, see our Privacy Policy, Terms of Service and Documents.

#Troubleshooting

#Support

Write to blumie@blumie.io. Include the client you use (for example Claude or Cursor), your organization's name and, if you can, the prompt that failed.