LLM-friendly URL

MCP server

Luzmo hosts a Model Context Protocol (MCP) server so you can add Luzmo IQ and chart generation to your own agents. Connect from frameworks such as the Claude Agent SDK, LangChain, or the OpenAI Agents SDK without building custom /aiprompt integrations yourself.

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

ℹ️

Note: Luzmo IQ is available as an add-on. You need a valid Embed/API key and token so the agent can access your data (in case of an Embed token, it also ensures any multitenancy is automatically applied on all queries).

URL

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

Region MCP URL
EU (default) https://api.luzmo.com/0.1.0/mcp
US https://api.us.luzmo.com/0.1.0/mcp
Custom VPC https://<your-vpc>-api.luzmo.com/0.1.0/mcp

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 search_datasets , answer_question , and create_chart

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

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

Authentication

Each MCP session can use either a Luzmo API key-token pair or an Embed key-token pair (required to securely expose the MCP server to end-users). The server resolves them 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")>

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 ):

mcp-config.json
json
{
  "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>

Regional host overrides (when needed): X-Luzmo-Api-Host , X-Luzmo-App-Url , or the matching query parameters.

Tools

If you omit the tools query parameter, the server registers exactly these three tools:

  • search_datasets

  • answer_question

  • create_chart

answer_question_text is not loaded by default. To enable it, pass an explicit tools list, for example: 

?tools=search_datasets,answer_question,answer_question_text,create_chart

To use a smaller subset, list only the tools you need, e.g. /mcp?tools=search_datasets,answer_question .

Tool Default Purpose
search_datasets Yes Used to browse or search datasets and schemas (read-only).
answer_question Yes Natural-language Q&A via Luzmo IQ ( analyst agent). Returns text and, when appropriate, chart configuration.
create_chart Yes Generate a chart from a prompt ( item agent).
answer_question_text No Text-only Q&A (no charts). Opt in via tools when the caller must never receive chart assets.

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.

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 serves standard MCP clients and MCP App clients.

Client type What you get
Plain MCP Tool text plus visualization item JSON in the result (and structuredContent when supported).
MCP App Same tool results, plus a live Luzmo visualization item in the host UI (when a visualization item is generated).

MCP App is useful whenever you want to display generated visualization items in your custom chat UI, or to display visualization items inside third party apps like Claude or ChatGPT.

Visualization item tools that can open the embed UI:

  • answer_question (when Luzmo returns a visualization item)

  • create_chart

search_datasets and answer_question_text stay text-only.

Did this page help you?
Yes No