MCP Server

Overview

Holistics provides an MCP server that lets your own AI agents access and perform BI tasks on your Holistics workspace.

Demo

Here is a demo where Claude Desktop uses Holistics MCP to build a business report:

Why MCP server?

It enables you to combine and leverage:

• Holistics resources and features
  • Data analytics resources: datasets, dashboards, etc.
  • Holistics features: Explore Data AI, create dashboards, export data, etc.
• Your own AI agent tool (e.g. Claude Desktop, Cursor, Slack bot) with:
  • Its reasoning and research capabilities
  • Other "tools" that you provided to it
  • etc.

Protocol

Holistics MCP server supports Streamable HTTP Transport with either OAuth or API Key Authentication.

Connection URL

Select options to build your connection URL:

App domain

APAC (secure.holistics.io)

Environment

Reporting

Connection URL

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

Development

Connection URL

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

US (us.holistics.io)

Environment

Reporting

Connection URL

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

Development

Connection URL

https://mcp-us.holistics.io/development/mcp

EU (eu.holistics.io)

Environment

Reporting

Connection URL

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

Development

Connection URL

https://mcp-eu.holistics.io/development/mcp

Custom domain

Connection URL

note

Please contact [email protected] for your MCP server address.

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)

Authentication

Either:

• OAuth: MCP clients that support OAuth will handle the authentication flow automatically when you connect
• API Key: via X-Holistics-Key HTTP header

How to connect

Prerequisites

1. Enable Holistics AI and MCP server in your Holistics workspace settings

2. Build your <MCP_SERVER_ADDRESS> connection URL — pick your data center region and target environment. For example: https://mcp-apac.holistics.io/reporting/mcp
3. (API Key auth only) Obtain a Holistics API key for <YOUR_HOLISTICS_API_KEY>

Using Claude.ai

Claude.ai connects to MCP servers via OAuth.

1. Click Customize in the left sidebar (or go to claude.ai/settings/connectors)

2. Click Add custom connector

   

3. Enter name and your <MCP_SERVER_ADDRESS>, then click Add

   

4. Click Connect and follow the OAuth flow to authenticate with your Holistics account

To use it in a chat, click the tools icon (to the left of the message field) and enable your connector under Connectors.

Using ChatGPT

ChatGPT connects to MCP servers via OAuth.

1. Open Settings > Apps, then click Advanced settings at the bottom

2. Toggle Developer mode on

   

3. Click Create app. Enter a name, your <MCP_SERVER_ADDRESS>, and select OAuth as the authentication method

   

4. Click Save — the app appears under Drafts in Settings > Apps

To use it in a chat, click + in the composer > More > Developer mode, then select your app.

Using Claude Code

Claude Code lets you add MCP servers with a single claude mcp add command.

With OAuth:

claude mcp add holistics-<ENV> <MCP_SERVER_ADDRESS> --transport http

With API Key:

claude mcp add holistics-<ENV> <MCP_SERVER_ADDRESS> --transport http --header "X-Holistics-Key:<YOUR_HOLISTICS_API_KEY>"

note

Do not leave any spaces between X-Holistics-Key: and <YOUR_HOLISTICS_API_KEY>.

Using remote url config

Example supported tools:

• Claude Code
• Cursor
• VS Code (NOTE: specify "servers" instead of "mcpServers")

Please refer to their linked docs for more details on how to configure.

With OAuth — the MCP client handles the authentication flow automatically:

{
  "mcpServers": {
    "holistics": {
      "url": "<MCP_SERVER_ADDRESS>"
    }
  }
}

With API Key:

{
  "mcpServers": {
    "holistics": {
      "url": "<MCP_SERVER_ADDRESS>",
      "headers": {
        "X-Holistics-Key": "<YOUR_HOLISTICS_API_KEY>"
      }
    }
  }
}

Using local command config

Example supported tools:

• Claude Desktop
• Claude Code
• Cursor
• VS Code (NOTE: specify "servers" instead of "mcpServers")

Please refer to their linked docs for more details on how to configure.

With OAuth — the MCP client handles the authentication flow automatically:

{
  "mcpServers": {
    "holistics": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<MCP_SERVER_ADDRESS>"
      ]
    }
  }
}

With API Key:

{
  "mcpServers": {
    "holistics": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<MCP_SERVER_ADDRESS>",
        "--header", "X-Holistics-Key:<YOUR_HOLISTICS_API_KEY>"
      ]
    }
  }
}

Note: Do not leave any spaces between X-Holistics-Key: and <YOUR_HOLISTICS_API_KEY>

Example: Claude Desktop

1. Go to Claude Desktop Settings > Developer > Edit Config
2. Input the above json into the config

Using OpenAI API

import OpenAI from "openai";
import type { ResponseInput } from 'openai/resources/responses/responses';

const client = new OpenAI({
  apiKey: "<YOUR_OPENAI_KEY>",
});

async function chat(input: ResponseInput) {
  const completion = await client.responses.create({
    model: "gpt-4.1",
    input: input,
    tools: [
      // Other tools
      {
        type: "web_search",
      },
      // BEGIN HOLISTICS MCP DECLARATION
      {
        type: "mcp",
        server_label: "holistics_mcp",
        server_url: "<MCP_SERVER_ADDRESS>",
        server_description: 'Holistics MCP to access my BI and business data',
        headers: {
          "X-Holistics-Key": "<YOUR_HOLISTICS_API_KEY>",
        },
        require_approval: "never", // optional
      },
      // END HOLISTICS MCP DECLARATION
    ],
    tool_choice: "auto",
    parallel_tool_calls: true,
  });

  console.log(completion.output_text)
}

Using a Slack (MCP Client) bot

See this guide Running a self-hosted Slack bot.

Troubleshooting

Verify that Holistics MCP server is enabled

You can use MCP Inspector to test your Holistics MCP server.

Steps:

1. Run MCP Inspector (in your terminal): npx @modelcontextprotocol/inspector
   • MCP Inspector will be automatically opened in your browser
2. Configure Holistics MCP:
   1. Choose Transport Type: Streamable HTTP
   2. Enter URL: <MCP_SERVER_ADDRESS>
   3. Configure Authentication — choose one:
      • OAuth: Click Connect and follow the OAuth flow
      • API Key: Select API Token Authentication, set Header Name to X-Holistics-Key, and enter your API key as the Bearer Token
3. Click Connect button
   • You should see "Connected" status below the button
4. Go to Tools tab -> Click List Tools
   • You should see the Tools listed