Slack Server AI Agent Template

⚠️ Beta Notice: This template demonstrates MCP functionality that is currently in beta and not yet widely available to all developers. The functionality shown here is being tested and may change before general availability.

This Bolt for JavaScript template demonstrates how to build AI Apps in Slack that leverage the Slack MCP server.

Models from OpenAI are used and can be customized for prompts of all kinds.

Setup

Before getting started, make sure you have a development workspace where you have permissions to install apps. If you don’t have one setup, go ahead and create one.

Developer Program

Join the Slack Developer Program for exclusive access to sandbox environments for building and testing your apps, tooling, and resources created to help you build and grow.

Installation

Create a Slack App

1. Open https://api.slack.com/apps/new and choose "From an app manifest"
2. Choose the workspace you want to install the application to
3. Copy the contents of manifest.json into the text box that says *Paste your manifest code here* (within the JSON tab) and click Next
4. Review the configuration and click Create

Clone the project

# Clone this project onto your machine
git clone https://github.com/slack-samples/bolt-js-slack-mcp-server.git

Environment Variables

Before you can run the app, you'll need to store some environment variables.

1. Rename .env.sample to .env.
2. Open your apps setting page from this list, click Basic Information in the left hand menu, then copy the following values into your .env file:

SLACK_CLIENT_ID=YOUR_APP_CLIENT_ID
SLACK_CLIENT_SECRET=YOUR_APP_CLIENT_SECRET
SLACK_SIGNING_SECRET=YOUR_APP_SIGNING_SECRET
SLACK_STATE_SECRET='your-state-secret'
SLACK_INSTALL_URL='https://<APP_INSTALLATION_URL>/slack/install'

Note: the SLACK_INSTALL_URL is where users initiate the installation of the app into their workspace. For more information about this URL, please see the OAuth section.

3. Unlock the OpenAI models from your OpenAI account dashboard by clicking create a new secret key, then save your OpenAI key into the .env file as OPENAI_API_KEY like so:

OPENAI_API_KEY=YOUR_OPEN_API_KEY

Local Project

# Change into the project directory
cd bolt-js-slack-mcp-server

# Install dependencies
npm install

# Run Bolt server
npm start

Linting

# Run lint for code formatting and linting
npm run lint

OAuth

This sample relies on the usage of user tokens, and therefore requires individual user installations to function as intended.

Reminder: the Bolt app must be running and the following endpoints made available for the below URLs to be accessible when updating them in the app configuration.

When using OAuth, Slack requires a public URL where it can send requests. In this template app, we've used ngrok. Checkout this guide for setting it up.

Start ngrok to access the app on an external network and create a redirect URL for OAuth.

ngrok http 3000

This output should include a forwarding address for http and https (we'll use https). It should look something like the following:

Forwarding   https://3cb89939.ngrok.io -> http://localhost:3000

Navigate to OAuth & Permissions in your app configuration and update the Redirect URL. The redirect URL should be set to your ngrok forwarding address with the slack/oauth_redirect path appended. For example:

https://3cb89939.ngrok.io/slack/oauth_redirect

Navigate to Event Subscriptions in your app configuration and update the Request URL. The request URL should be set to your ngrok forwarding address with the slack/events path appended. For example:

https://3cb89939.ngrok.io/slack/events

The value set for the SLACK_INSTALL_URL in .env corresponds to the public URL where users initiate the installation of the app into their workspace. The install URL should be set to your ngrok forwarding address with the slack/install path appended. For example:

https://3cb89939.ngrok.io/slack/install

Usage

After installing the app into a workspace using the OAuth installtion flow, create a new chat (via DM) with the chatbot.

Upon creation of the new chat, the user is prompted with two static options that demonstrate either sending a message to #general, or creating a new canvas – both as and on behalf of the user.

Project Structure

manifest.json

manifest.json is a configuration for Slack apps. With a manifest, you can create an app with a pre-defined configuration, or adjust the configuration of an existing app.

app.js

app.js is the entry point for the application and is the file you'll run to start the server. This project aims to keep this file as thin as possible, primarily using it as a way to route inbound requests.

/listeners/assistant

Configures the new Slack Assistant features, providing a dedicated side panel UI for users to interact with the AI chatbot. This module includes:

• The assistant-thread-started.js file, which responds to new app threads with a list of suggested prompts.
• The assistant-thread-context-changed.js file, which updates the context to include information about where the conversation with the chatbot is occurring (i.e., in a DM or within a channel).
• The user-message.js file, which responds to user messages sent to app threads or from the Chat and History tab with an LLM generated response.

/llm

The openai.js file handles the OpenAI API initialization and configuration.