MCP server

Luzmo hosts a Model Context Protocol (MCP) server that gives AI agents access to Luzmo IQ, chart generation, and your Luzmo content. It supports two use cases:

Work with the Luzmo platform
Connect an AI client such as Claude, ChatGPT, or Cursor to your Luzmo organization to ask questions about your data, create charts, and manage dashboards, datasets, and formulas. Log in with your Luzmo account (OAuth flow), or authenticate with an API key and token.

Embedded: Add Luzmo analytics to your own agent or MCP server
Give your own agent, or your own branded MCP server, Luzmo's data Q&A and chart generation for your end-users. Authenticate with an Embed key and token per end-user, so each user only gets access to their own data. Connect from frameworks such as the Claude Agent SDK, LangChain, or the OpenAI Agents SDK without building custom /aiprompt integrations yourself.

The login method also sets the default tools of the session (see Tools ).

For step-by-step agent loops, token handling, and framework examples, see Adding Luzmo IQ to your agentic workflow .

URL

Point your MCP client at the Luzmo API host for your region or VPC:

Use credentials issued for the same region or VPC as the API host. For production setups, pass your API/Embed key and token via headers or Basic Auth , not in the URL.

Optional query parameters:

• tools : override the default tool set (see Tools ); omit to use the default for your credential type

• permissions : limit which kinds of tools the session gets: read-only , non-destructive , or full (see Permissions )

• agentId : run answers and charts through a saved Agent (see Saved Agent )

• themeId : default chart theme for the session (see Visualization item themes )

• luzmo_app_url : override app hosts per session (necessary for charts to correctly render)

Authentication

Each MCP session authenticates with a Luzmo API key-token pair (including SSO and technical-user tokens), an Embed key-token pair (required to securely expose the MCP server to end-users), or a Luzmo login (OAuth flow). The server resolves key-token pairs in this order:

1. URL query: authKey and authToken

2. Headers: authKey and authToken , or X-Luzmo-Key and X-Luzmo-Token

3. HTTP Basic Auth: Authorization: Basic <base64("key:token")>

If no key and token are provided, the server starts the Luzmo OAuth flow: the MCP client asks the user to log in to Luzmo and grant access.

Prefer headers or Basic Auth in production. Query parameters work for quick local testing but can appear in access logs, browser history, and referrer headers.

MCP client config

Use this configuration when connecting an MCP client to Luzmo. The client sends authKey and authToken as headers on each MCP request (aliases: X-Luzmo-Key and X-Luzmo-Token ):

{
  "mcpServers": {
    "luzmo": {
      "type": "http",
      "url": "https://api.luzmo.com/0.1.0/mcp",
      "headers": {
        "authKey": "<api-key>",
        "authToken": "<api-token>"
      }
    }
  }
}

HTTP Basic Auth

Encode your key and token as base64("key:token") and send it as an Authorization header on the /mcp request:

POST /mcp

POST /0.1.0/mcp HTTP/1.1
Host: api.luzmo.com
Authorization: Basic <base64("key:token")>

URL query parameters

For quick testing only, you can pass credentials in the query string:

/mcp?authKey=<embed-key>&authToken=<embed-token>

Tools

The tools a session gets by default depend on the credentials it authenticates with:

An Embed token represents a single end-user, so it only gets the tools to ask questions and chart the answers. For OAuth logins, the default is further narrowed to the scopes the token was granted.

To override the default, pass an explicit tools list. A listed tool is registered whatever the credentials, as long as the permissions mode allows it (see Permissions ); whether a call then succeeds is decided by the rights of those credentials. For example, to give an Embed session the option to save charts to a dashboard:

?tools=search_datasets,answer_question,create_chart,list_dashboards,add_chart_to_dashboard

answer_question_text is never loaded by default. To enable it, list it explicitly:

?tools=search_datasets,answer_question,answer_question_text,create_chart

Model guidance: Prefer answer_question for analytics questions. It already returns text-only when Luzmo cannot build a chart. Use answer_question_text only when charts must be disabled. Call search_datasets when browsing datasets or resolving IDs is required.

Chart tools may include a conversation_id for follow-up questions in the same thread.

Permissions

Use the permissions query parameter to limit which kinds of tools a session gets, based on their impact:

?permissions=read-only
?tools=search_datasets,answer_question,create_chart&permissions=read-only

Tools the mode does not allow are hidden, and calls to them are refused. The server returns HTTP 400 when:

• permissions is not one of the three modes above.

• None of the tools in your tools list are allowed by the mode, so the session would have no tools left. For example, ?tools=update_formula,delete_formula&permissions=read-only .

permissions limits what the MCP offers the model; it is not an access-control boundary. What a session can actually read or write is always decided by its credentials (and, for OAuth, the granted scopes).

Saved Agent

To answer questions and generate charts with a saved Luzmo Agent, pass its id as agentId in the MCP URL:

https://api.luzmo.com/0.1.0/mcp?agentId=<agent-uuid>

Create and manage Agents on the Agents page of the Luzmo app. Each tool keeps its own agent ( answer_question and answer_question_text use the analyst, create_chart the item agent) and adds the Agent's rules and datasets. Your MCP client stays the orchestrator.

The Agent's capabilities narrow the default tools of your credentials; they never add tools the credentials don't get by default:

• An Agent without capabilities offers all the tools above.

• Workspace tools such as create_dataset , update_dataset_* , the formula tools, list_connections , create_embed_credentials , and search_docs are not offered by default, and neither is answer_question_text . Add them with an explicit tools list, which replaces the default tool set. When the Agent has datasets, create_dataset and update_dataset_sql are refused, and create_embed_credentials cannot grant collections, because they could reach data outside the Agent.

• When the Agent has data analysis but not chart creation, answer_question answers in text only.

If the Agent has datasets, every tool is limited to them: search_datasets only returns the Agent's datasets, and a tool called with another dataset returns an error that lists the available ones. Formulas count too: a chart or formula that reads another dataset through a formula is refused, even when its own dataset belongs to the Agent. This is checked on every call, so changes to the Agent's datasets apply straight away. An Agent without datasets doesn't limit them.

The agentId is fixed when the session initializes and must be a UUID; an invalid value, or an Agent the credentials can't use, returns HTTP 400 . The tool list is set when the session starts. A themeId (in the URL, header, or tool call) still overrides the Agent's theme.

Visualization item themes

Set a default Luzmo theme for visualization items created in the session:

1. URL: themeId (alias luzmo_theme_id )

2. Header: X-Luzmo-Theme-Id

3. Per tool call: optional themeId argument (overrides the session default)

Use a custom theme UUID from your Luzmo account, or a built-in platform id : default , default_dark , vivid , seasonal , orion , royale , urban , pinky , bliss , radiant , classic , classic_dark . See this Academy article on how to create and manage themes.

Example (URL parameter):

https://api.luzmo.com/0.1.0/mcp?themeId=<theme-uuid>

Or send X-Luzmo-Theme-Id: <theme-uuid> as a header alongside your auth headers.

Invalid theme values return HTTP 400 .

MCP App

The same /0.1.0/mcp endpoint supports the MCP App extension on hosts that can render interactive UI from tool results.

Use cases

• Your own chat UI : If you already have a chat interface that supports MCP App, connect Luzmo's MCP server to show generated charts inline.

• Third-party apps (e.g. Claude, ChatGPT) : Expose your own MCP connector to your users and use Luzmo's MCP under the hood to add data analysis and interactive chart visualization. Your MCP sits in front of Luzmo's (or wraps it) so users can ask questions and view charts inside those hosts without you building custom /aiprompt integrations.

Third-party example: Claude app

In production, run your own MCP server in front of Luzmo's: authenticate your users, mint a Luzmo Embed key and token per user or session on your backend, and forward requests to Luzmo's MCP with those credentials. End users never see or manage Luzmo keys.

To preview the end-user experience, connect directly to the Luzmo MCP in your own Claude account:

1. In the Claude app, open Integrations → Connectors .

2. Click + , then Add custom connector .

3. Enter the Luzmo MCP URL with a valid API or Embed key and token:

https://api.luzmo.com/0.1.0/mcp?authKey=<API/Embed key>&authToken=<API/Embed token>

Related documentation

• Adding Luzmo IQ to your agentic workflow : agent loops, MCP config examples, OpenAI Agents SDK, LangChain

• AIPrompt : underlying Core API used by MCP chart and Q&A tools

• API overview : all Luzmo APIs