Skip to main content

Claude Code

Try Holistics CLI + Skills

For coding agents, the recommended setup is the Holistics CLI + Skills workflow rather than a standalone MCP connection. It sets up local AML development, CLI sync, and MCP access together in one step — the full local development experience, not just data Q&A.

Overview​

Here's what you'll do to connect Claude Code to Holistics:

  • Turn on MCP Server - a one-time step in your Holistics workspace, done by an admin. If it's already on, skip ahead.
  • Get your connection URL: choose the environment you want to work with
    • Reporting: published Holistics objects - those on the Reporting tab.
    • Development: unpublished Holistics objects in your current AMQL project branch - those on the Development tab.
  • Choose your connection method:
    • CLI command is the quickest way to register the server from your terminal.
    • JSON config is useful if you're already managing other MCP servers in a config file.
  • Choose your authentication method:
    • OAuth logs in with your Holistics account - no key to create or manage.
    • API key uses a static key instead, useful for headless or scripted setups.
    • Learn more: OAuth vs. API key - which should I use?
  • Install Holistics skills: add the Holistics plugins so Claude Code knows how to work with Holistics.

Step 1: Turn on MCP Server​

This is a one-time setup done by a workspace admin. Go to AI Settings and enable both Holistics AI and the MCP Server.

ai-mcp-setting

Step 2: Get your connection URL​

Your connection URL depends on your data center region and the Holistics environment you want your AI to work with.

Select your data region

Select your working environment

Let your AI work with published Holistics objects — those on the Reporting tab.

Get your connection url

https://mcp-apac.holistics.io/reporting/mcp


URL format
https://mcp-<REGION>.holistics.io/<ENV>/mcp
  • <REGION>: Choose based on your data center: apac, eu, or us
  • <ENV>:
    • reporting (default): Let your AI work with published Holistics objects (i.e. objects on your Holistics Reporting tab)
    • development: Let your AI work with unpublished Holistics objects in your current AMQL project branch (i.e. objects on your Holistics Development tab)

Step 3: Connect​

Claude Code supports two ways to register the Holistics MCP server: CLI command and JSON config. Both support OAuth and API key.

CLI command​

OAuth​

  • Use your connection URL from Step 2 and replace <MCP_SERVER_ADDRESS>.
claude mcp add holistics-<ENV> <MCP_SERVER_ADDRESS> --transport http

API key​

  • Use your connection URL from Step 2 and replace <MCP_SERVER_ADDRESS>.
  • Obtain your API key:

Find your key under profile menu > User settings in Holistics.

Holistics profile menu with the User settings option highlighted
  • Replace <YOUR_HOLISTICS_API_KEY> below with it.
claude mcp add holistics-<ENV> <MCP_SERVER_ADDRESS> --transport http --header "X-Holistics-Key:<YOUR_HOLISTICS_API_KEY>"

Note: No spaces between X-Holistics-Key: and your API key.

JSON config​

Add to your Claude Code MCP config.

OAuth​

  • Use your connection URL from Step 2 and replace <MCP_SERVER_ADDRESS>. Omit the headers field — the client handles authentication automatically.
{
  "mcpServers": {
    "holistics": {
      "url": "<MCP_SERVER_ADDRESS>"
    }
  }
}

API key​

  • Use your connection URL from Step 2 and replace <MCP_SERVER_ADDRESS>
  • Use the same API key as obtained above, and replace <YOUR_HOLISTICS_API_KEY> below with it.
{
  "mcpServers": {
    "holistics": {
      "url": "<MCP_SERVER_ADDRESS>",
      "headers": {
        "X-Holistics-Key": "<YOUR_HOLISTICS_API_KEY>"
      }
    }
  }
}

Step 4: Install Holistics skills​

Holistics skills teach Claude Code how to work with Holistics, such as exploring datasets and writing AQL. Run these commands one at a time (Claude Code only accepts one slash command per submission).

Add the Holistics marketplace:

/plugin marketplace add holistics/skills

Then install the plugins you need, one command at a time.

To develop your AMQL project (models, datasets, and dashboards):

/plugin install holistics-development@holistics-skills

To ask data questions on published datasets and dashboards:

/plugin install holistics-reporting@holistics-skills

To keep plugins up to date, go to /plugin → Marketplaces → holistics-skills → Enable auto-update.

For more details, see Anthropic's guide: Install and manage plugins.

Configure AQL & Viz authoring​

The holistics-development (0.9.0 or later) and holistics-reporting (0.2.0 or later) plugins have an AQL & Viz authoring option. It decides whether Holistics AI or Claude Code writes AQL and visualizations. See Choose who writes AQL and visualizations for how each option works and is billed.

  1. Run /plugins.
  2. Go to the Installed tab and type holistics.
  3. Select your plugin and press Enter.
  4. Go to Configure options.
  5. Under AQL & Viz authoring, choose holistics-ai (default) or self.
  6. Select Save configuration.

Need more help?​

See the MCP FAQ for questions about permissions, data access, and security.

Open Markdown
Let us know what you think about this document :)