# Build an AI chatbot in Slack

> Run a self-hosted Slack bot that connects to Holistics MCP so your team can query data directly from Slack.

## Introduction
This guide walks you through running your own Slack bot that connects to [Holistics MCP server](/docs/ai/mcp-server/capabilities), enabling your team to chat with your Holistics data on Slack.

:::warning DISCLAIMER
This guide uses open-source code (https://github.com/tuannvm/slack-mcp-client) as an example to implement the Slack bot.
* This code is not owned or developed by Holistics. Thus, Holistics does not take responsibility for issues related to this code.
* You can implement your own code instead of using it.
:::

## Architecture

* **Slack workspace**: The workspace where you and your users will be chatting with the Slack bot.
* **Slack App**: Slack's configuration for your bot, including how the bot is connected, how the bot appears, what the bot is allowed to do.
* **Slack Bot**: The bot runtime that listens and responds to Slack messages.
    * It uses the LLM from the LLM provider to write responses and prepare tool calls.
    * It executes the tool calls on the MCP servers.
* [**Holistics MCP Server**](/docs/ai/mcp-server/capabilities): The server that accepts the Bot's tool call requests to perform analytical tasks on Holistics and return the result to the Bot.

## Walkthrough
### A. Set up your LLM provider
Obtain an API key from your LLM provider. It will be used to power the bot's ability to chat and use Holistics.

LLM providers supported by slack-mcp-client: OpenAI, Anthropic, Ollama.

### B. Create a Slack App for your bot
1. Visit https://api.slack.com/apps
2. Click **Create New App**

    
    * You can name it `Holistics AI Agent` or even `<Your Company> AI Agent` (because you can connect the Slack bot to multiple MCP servers, not just Holistics!)
    * Make sure to choose the Slack workspace where you will use the Slack bot
3. Go to **OAuth & Permissions** and add these **Bot Token Scopes**:
    * `app_mentions:read`
    * `chat:write`
    * `im:history`
    * `im:read`
    * `im:write`
    * `users:read`
    * `users.profile:read`
    * `channels:history`
    * `groups:history`
    * `mpim:history`
4. Enable **Socket Mode**
    
5. Enable **Event Subscriptions** and subscribe to these events (make sure to click **Save changes**):
    * `app_mention`
    * `messages.im`

    
6. Go to **App Home** and enable **Messages Tab**:
    
7. Go to **OAuth & Permissions** and click **Install to &lt;Your workspace&gt;** under **OAuth Tokens**
8. Obtain Slack tokens:
    * Bot token: In **OAuth & Permissions** tab, under **OAuth Tokens**
    * App-level token: In **Basic Information** tab, under **App-Level Tokens**

### C. Set up Holistics MCP Server
1. Enable Holistics AI and MCP server in your Holistics workspace [settings](/docs/ai/ai-settings)

2. Obtain a [Holistics API key](/api/v2/getting-started) and store it securely. Your Slack bot will use this API key for MCP Server authorization.

### D. Set up Slack bot
1. [Install slack-mcp-client](https://github.com/tuannvm/slack-mcp-client#installation)
    * You can go to https://github.com/tuannvm/slack-mcp-client/releases/latest and download the binary that is compatible with your OS.
2. Create a folder named `slack-bot` to store your configs.
3. Create `config.json` inside `slack-bot`:
    ```json
    {
      "$schema": "https://github.com/tuannvm/slack-mcp-client/blob/main/schema/config-schema.json",
      "version": "2.0",
      "slack": {
        "botToken": "${SLACK_BOT_TOKEN}",
        "appToken": "${SLACK_APP_TOKEN}"
      },
      "llm": {
        "provider": "openai",
        "useNativeTools": true,
        "useAgent": true,
        "customPromptFile": "./prompt.txt",
        "providers": {
          "openai": {
            "model": "gpt-4.1",
            "apiKey": "${OPENAI_API_KEY}",
            "temperature": 0.2
          }
        }
      },
      "mcpServers": {
        "holistics": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://mcp-<region>.holistics.io/mcp",
            "--header",
            "X-Holistics-Key:${HOLISTICS_API_KEY}"
          ],
          "env": {
            "HOLISTICS_API_KEY": "${HOLISTICS_API_KEY}"
          }
        }
      }
    }
    ```

    **NOTE**:
    * Replace the connection URL placeholder with your [connection URL](/docs/ai/mcp-server/setup#oauth).
    * Configure `providers` according to your LLM provider.
4. Create `.env` inside `slack-bot`:
    ```shell
    SLACK_BOT_TOKEN="xoxb..."        # from step B.8
    SLACK_APP_TOKEN="xapp..."        # from step B.8
    OPENAI_API_KEY="..."             # from step A
    HOLISTICS_API_KEY="..."          # from step C.2
    ```
5. Create `prompt.txt` inside `slack-bot`:
    ```md
    # Holistics
    You have access to the Holistics MCP (Model Context Protocol) tool, which provides powerful data analytics and business intelligence capabilities. Here's how to use it effectively:
    ## When to Use Holistics MCP:
    - When users ask about business metrics, KPIs, or data analytics.
    - When users need specific numbers, trends, or insights from company data.
    - When users request insight information or detailed data.
    - When users want to explore available datasets or understand data relationships.
    ## Best Practices:
    1. **Be Specific**: When querying data, be as specific as possible with date ranges, filters, and dimensions.
    2. **Handle Errors Gracefully**: If the MCP tool returns an error, display the original error message, explain what might have gone wrong and suggest alternatives.
    3. ALWAYS check the actual dataset names using list_datasets tool.
    4. Combine answers from multiple datasets if one is not enough.
    ## Response Format:
    When using the Holistics MCP tool:
    - ALWAYS include the dataset name (wrapped inside \`\`) in your response.
    - Clearly state what data you're retrieving.
    - Present results in a clear, formatted manner.
    - Include relevant context about the time period, filters applied, and which specific datasets were used.
    - If it makes sense, you can provide an inline markdown table (inside a markdown quoted block, suitable for Slack formatting) to visualize the result.
    - If the result has any links, include them in your response.
    ```
### E. Run and test your Slack bot
Run your slack bot in terminal:
```bash
# within slack-bot folder (created in step D.2)
slack-mcp-client
```

Test by chatting in your Slack workspace:

### F. What's next
* Deploy your Slack bot to a server to let it run 24/7
* Customize `prompt.txt` to suit your needs better
* Connect your Slack bot to other MCP servers (e.g. Notion, Linear, etc.) by configuring `config.json`