# Set up

> Connection details and troubleshooting for the Holistics MCP Server.

## Enable MCP server

This is a one-time setup done by a workspace admin. Go to [AI Settings](/docs/ai/ai-settings) and enable both **[Holistics AI](/docs/ai/enable-ai)** and the **MCP Server**. 

## Authentication

Holistics MCP supports two authentication methods. Choose the one that best fits your needs:

| | OAuth (recommended) | API key |
|---|---|---|
| **Best for** | Individual users connecting under their own Holistics identity | Admins managing keys centrally, or automated workflows |
| **Setup complexity** | Low — browser login flow | Medium — manual configuration |
| **Key management** | Automatic | Manual |
| **User permissions** | Uses your Holistics account permissions | Uses the API key owner's permissions |

### OAuth

<VideoPlayer src="https://cdn.holistics.io/product/ai-mcp-oauth-20260518-894.mp4" autoPlay={false} />

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

App domain

<Tabs groupId="holistics-region" queryString className="tabs--button">
  <TabItem value="apac" label="APAC (secure.holistics.io)">
    Environment
    <Tabs groupId="holistics-env" queryString className="tabs--button">
      <TabItem value="reporting" label="Reporting">
        Let your AI work with published Holistics objects — those on the Reporting tab.
        Connection URL

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

      </TabItem>
      <TabItem value="development" label="Development">
        Let your AI work with unpublished Holistics objects in your current AMQL project branch — those on the Development tab.
        Connection URL

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

      </TabItem>
    </Tabs>
  </TabItem>
  <TabItem value="us" label="US (us.holistics.io)">
    Environment
    <Tabs groupId="holistics-env" queryString className="tabs--button">
      <TabItem value="reporting" label="Reporting">
        Let your AI work with published Holistics objects — those on the Reporting tab.
        Connection URL

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

      </TabItem>
      <TabItem value="development" label="Development">
        Let your AI work with unpublished Holistics objects in your current AMQL project branch — those on the Development tab.
        Connection URL

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

      </TabItem>
    </Tabs>
  </TabItem>
  <TabItem value="eu" label="EU (eu.holistics.io)">
    Environment
    <Tabs groupId="holistics-env" queryString className="tabs--button">
      <TabItem value="reporting" label="Reporting">
        Let your AI work with published Holistics objects — those on the Reporting tab.
        Connection URL

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

      </TabItem>
      <TabItem value="development" label="Development">
        Let your AI work with unpublished Holistics objects in your current AMQL project branch — those on the Development tab.
        Connection URL

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

      </TabItem>
    </Tabs>
  </TabItem>
  <TabItem value="custom" label="Custom domain">
    Connection URL

    :::note
    Please contact [support@holistics.io](mailto:support@holistics.io) for your MCP server address.
    :::

  </TabItem>
</Tabs>

<details>
<summary>URL format</summary>

```
https://mcp-<REGION>.holistics.io/<ENV>/mcp
```

* **`<REGION>`**: Choose based on your [data center](/docs/security-compliance/data-centers#how-do-i-know-which-data-center-im-on): `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)

</details>

### API key

Pass a Holistics API key via the `X-Holistics-Key` HTTP header. It's long-lived and requires no login flow. Find your key under **Account settings** in Holistics.

## Test and troubleshoot

If your AI tool can't connect, use [MCP Inspector](https://modelcontextprotocol.io/legacy/tools/inspector) to test the server directly.

1. Run MCP Inspector in your terminal:
   ```bash
   npx @modelcontextprotocol/inspector
   ```
   It opens automatically in your browser.

2. Configure the connection:
   - **Transport Type**: `Streamable HTTP`
   - **URL**: your connection URL from above
   - **Authentication** — choose one:
     - **OAuth**: click **Connect** and follow the OAuth flow
     - **API Key**: select **API Token Authentication**, set **Header Name** to `X-Holistics-Key`, enter your API key as the **Bearer Token**

3. Click **Connect** — you should see "Connected" status.

4. Go to the **Tools** tab and click **List Tools** — you should see the available Holistics tools.

If you still can't connect, verify that Holistics AI and MCP Server are enabled in your [AI Settings](/docs/ai/ai-settings) and that your API key is valid (in case you use API).