Skip to main content

Connecting an MCP server to the Slackbot MCP Client

The Slackbot MCP Client allows developers to connect remote MCP servers via HTTP to Slack. Once connected, Slackbot will automatically discover your MCP server's tools and invoke them based on user prompts in conversation.

You can add MCP server support via a Slack app, like any other Slack platform feature. Within this guide, you'll determine the proper authentication method for your MCP server, configure it within a Slack app, and then install said app to a workspace. By the end, you'll be able to invoke the tool from Slackbot.

Choosing the proper authentication method​

Slack supports four authentication methods for MCP server requests. Choose the one that fits your use case and the MCP server you plan to use.

Authentication methodUsePer-user identityRequires separate OAuth flow
No authUse when your MCP server serves the same responses regardless of who is asking. Users can start using tools immediately with no OAuth flow.NoNo
Slack identity authUse when your MCP server maps Slack user IDs and team IDs to available features. No separate OAuth flow is required for end users; Slack identifies them via signed requests containing their user and team IDs.Yes (Slack user/team ID)No
Dynamic Client RegistrationUse when connecting to a third-party MCP server that supports DCR. You provide the URL and the server handles OAuth client registration automatically.Yes (OAuth tokens)Yes
Manual OAuthUse when your MCP server doesn't support DCR. You define the authorization URL, token URL, scopes, and identity endpoint. When a user connects in Slackbot, Slack redirects them through the provider's OAuth flow using these credentials.Yes (OAuth tokens)Yes

Adding the MCP server to your Slack app​

You can configure your MCP server within App Settings or by editing the app manifest directly. If you add a server via App Settings, those settings are automatically added to the manifest.

  1. Go to your app at api.slack.com/apps. If you don't already have one, create one by clicking Create New App.

  2. In the left sidebar under Features, click MCP Servers.

  3. Click the Get Started button to open the MCP Server form.

  4. Fill in the following fields:

    • Name: A display name for your MCP server.
    • URL: The HTTPS endpoint of your MCP server (e.g., https://mcp.acme.com/mcp).
    • Auth Type: Select your desired authentication.

  5. Complete any additional fields required by your selected auth type, then click Save. The fields depend on the auth type you chose:

There are no additional fields. Slack identifies the user from signed requests.

Once saved, your MCP server appears in the MCP Server Connection Details table. You can add additional servers by clicking + Add MCP Server.

Adding an MCP server via App Settings automatically adds the mcp:connect scope to your app.

Register an OAuth client with your provider​

If you're using Manual OAuth, register an OAuth client with your provider before you configure the server above. When registering, set the redirect URI to Slack's external auth callback endpoint:

https://oauth2.slack.com/external/auth/callback

This is where the provider sends users after they authorize. The provider then issues a client_id and client_secret for the client, which you supply when you configure the server. If your provider needs to identify Slack as a client during registration, Slack publishes a Client ID Metadata Document (CIMD) at:

https://slack.com/.well-known/oauth-client-metadata

When editing the manifest directly, the client_secret is not stored in the manifest. Add it separately through the MCP Servers section in App Settings or with the Slack CLI:

slack external-auth add-secret

If your provider uses PKCE (use_pkce: true) and your provider key starts with mcp_, no client secret is required.

Implementing your MCP server​

MCP servers must use the Streamable HTTP transport.

The deprecated standalone HTTP+SSE transport and stdio are not supported. SSE-formatted responses within Streamable HTTP are supported and expected.

How you implement your MCP server will depend on the type of authentication your MCP server is using.

Using Slack identity auth​

The snippets below use either Bolt for JavaScript or Bolt for Python, alongside the Slack CLI

View the full examples: JavaScript | Python

In this example, three things happen on each request:

  1. The /mcp route verifies the Slack request signature.
  2. The tool reads the caller's identity from _meta.slack (provided automatically by Slack).
  3. The bot token from the installation store calls the users.info API method.

The _meta.slack identity fields​

When a tool is called through Slack identity auth, Slack attaches the caller's identity to the request under the _meta.slack object, nested inside the JSON-RPC request's params. These fields let your MCP server identify who is calling without requiring a separate OAuth flow. Read them from the _meta argument that Slack passes to your tool handler.

A tools/call request from a standalone workspace looks like this:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_profile_card",
    "arguments": {
      "user_id": "U0101010101"
    },
    "_meta": {
      "slack": {
        "user_id": "U01234ABCDE",
        "team_id": "T01234ABCDE",
        "enterprise_id": null
      }
    }
  }
}
FieldTypeDescription
user_idstringThe ID of the Slack user who invoked the tool. Pass it to the users.info method to look up profile data.
team_idstring or nullThe workspace ID for a standalone workspace. The value will be null for an Enterprise org user, unless the tool call resolves to a specific workspace where the app is installed.
enterprise_idstring or nullThe org ID for an Enterprise org user. The value will be null for a standalone workspace.

All three keys are always present in the object, but team_id and enterprise_id can be null. The combination tells you where the request came from:

Scenariouser_idteam_identerprise_id
Standalone workspaceU01234ABCDET01234ABCDEnull
Enterprise org, resolved to a workspaceU01234ABCDET01234ABCDEE01234ABCDE
Enterprise org, not resolved to a workspaceU01234ABCDEnullE01234ABCDE

Verify the request signature before trusting anything in _meta.slack. The field is ordinary request JSON and can be forged by any caller that reaches your endpoint, so its contents mean nothing until you've verified the X-Slack-Signature header. Once verified, read user_id and handle a null team_id when building the installation lookup. Slack attaches _meta.slack for all auth types so its presence alone tells you nothing about how the request was authenticated.

src/app.js
ai/slackbot-mcp-client/slack-identity/src/app.js
loading...

Entry point​

Start the server on the configured port. The Bolt app handles OAuth install and redirect routes alongside your MCP endpoint.

app.js
ai/slackbot-mcp-client/slack-identity/app.js
loading...

Setup​

  1. Expose your local server with ngrok. Update the url in your manifest with the generated URL.

    ngrok http 3000

  2. Install the app:

    1. Go to App Settings.
    2. Navigate to OAuth & Permissions > Install to Workspace (or Install to Organization for Enterprise).
    3. Authorize the app.

  3. Update environment variables with values from App Settings.

    The signing secret verifies that incoming requests originated from Slack. The state secret secures the OAuth install flow.

    ai/slackbot-mcp-client/slack-identity/.env.example
    loading...
    slack env init

  4. Start the app:

    slack run
Tools must respond within 60 seconds

If your MCP server doesn't return a result within 60 seconds, Slackbot aborts the call and surfaces an error to the user.

Using Slackbot​

  1. Open a DM with Slackbot.

  2. Click the Apps button in the Slackbot toolbar.

    The Slackbot toolbar showing the apps button

  3. On first use, a list of suggested apps appears. Click the + button next to the app to add it. Users can have up to 5 active MCP servers at a time.

  4. If using OAuth, you will be redirected to authorize with the partner's platform.

  5. Once connected, the app appears under Your apps in the Integrations tab with a Manage button.

Check if Slackbot detects your tool​

Ask Slackbot a question that maps to one of your tools:

What tools are available from Acme?

Slackbot will query your MCP server's tool definitions and list all available tools with descriptions.

You can also verify your tools by clicking Manage next to your app in the Integrations tab to view the list of available tools and their associated permissions.

Have Slackbot use a tool​

Try a natural language prompt:

Show me recent activity on my Acme account

Slackbot will select the appropriate tool. If the tool is from a third-party, the user must explicitly authorize each tool call, both read and write, before Slackbot executes it.

When Slackbot invokes a tool, users are presented with the following options:

  • Allow once: permits this tool call one time.
  • Always allow: permits all future calls to this tool without prompting.
  • Deny: blocks this tool call.

Users can view and update their tool permissions at any time in the MCP config dialog. After making a selection, Slackbot will then invoke the tool and return the results.

You can report responses with hallucinated information by clicking the thumbs down button. Then check the boxes next to the issues you want to report, and include the messages in your conversation if you’d like. We’ll always receive the last message you sent to Slackbot as part of a report. These reports help us identify patterns and improve Slackbot.

Enrich your tool responses​

By default, tool results appear as plain text. To create a more polished experience, your MCP server can return rich responses using Block Kit for native Slack layouts or interactive HTML/JS via MCP Apps.

Troubleshooting​

Viewing logs​

You can view debug logs for your MCP server connections and tool calls via App Settings. In the left sidebar under Features, click MCP Servers, then select the Logs tab. The logs only include activity from app collaborators.

MCP connector not appearing in Slackbot​

Check the following:

  • the app has mcp:connect in its bot scopes.
  • the MCP server is configured via an app manifest or App Settings.

Then try reinstalling the app after making any changes. On an Enterprise org, an org-level installation isn't required, but it can be useful when you want the app available across all workspaces in the org rather than installed workspace by workspace.

Slackbot failed to load tools​

Your MCP server may be rejecting authentication. If your app is using OAuth, ensure the user has completed the authorization flow.

You can also test your MCP endpoint directly:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "test", "version": "1.0"}
    }
  }' \
  https://mcp.acme.com/mcp

Slackbot discovers but does not invoke tools​

The tools may be unclassified and default to write classification. Ensure your tools include proper descriptions and classification metadata so that read-only tools execute without additional unnecessary confirmation prompts.

The invalid_client error​

After connecting an MCP server that supports Dynamic Client Registration (DCR), Slackbot may return an invalid_client error when calling the server. This can happen when the remote MCP server no longer recognizes the client_id that Slackbot registered with it. This typically happens when a self-hosted server stores OAuth client registrations and tokens only in memory. A server restart wipes that registration, so any client_id issued before the restart becomes invalid.

Disconnecting and reconnecting the MCP server in Slackbot does not force a new client registration. It retries the OAuth flow using the same client_id as before. If the server still doesn't recognize it, the error will persist, making the issue look intermittent. It may "resolve" on a retry only if the underlying token/session happens to still be valid.

To force re-registration, edit the MCP server connection and change the server URL (even temporarily), then save. Slackbot only performs a fresh client registration when the server URL changes; reusing the identical URL always reuses the existing client_id.

We recommend persisting OAuth client registrations and tokens to durable storage rather than memory only, so a server restart doesn't invalidate client_ids that Slack clients (including Slackbot) are still using.

OAuth errors​

If using manual OAuth, see the manual OAuth troubleshooting section above.

Onward​

By following along, you'll have an app that connects an MCP server to Slackbot for your users to interact with. But there's always more!

✨ To have visually graceful, interactive experiences, check out returning rich responses.

✨ To set up workspace controls, check out admin approval to manage how users install and access your app.

✨ To publish your app, check out distributing the app on the Slack Marketplace.