Skip to content

docs: align Slack setup guide with current Control Plane UI #218

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AshGodfrey merged 1 commit into from
Sep 30, 2026
Merged

docs: align Slack setup guide with current Control Plane UI #218

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 56 additions & 37 deletions guides/slack/speakeasy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,49 +2,68 @@

### Add the server in Speakeasy {#add-server-in-speakeasy}

1. In the Speakeasy AI Control Plane sidebar, under **Connect**, select **Sources**.
2. Click **Add Source**.
3. Choose **Custom remote server**.
4. On **Add a custom remote MCP server**, paste `https://mcp.slack.com/mcp`
into **Remote MCP server URL**.
5. Click **Add server**.
1. In the Speakeasy AI Control Plane sidebar, under **MCP Gateway**, select **MCP**.
2. Click **Add new** to open the **Add MCP server** page.
3. Choose **Hosted remotely**.
4. On **New remote MCP server**, paste this value into **MCP server URL**:

```
https://mcp.slack.com/mcp
```

5. Optionally enter a **Display name (optional)**.
6. Click **Verify connectivity**, then, after verification succeeds, click **Save**.

This creates the hosted MCP server and opens its **Overview** page.

<!-- screenshot: Add a custom remote MCP server with Slack's endpoint entered -->
<!-- screenshot: New remote MCP server with Slack's endpoint entered -->

### Connect your credentials {#connect-speakeasy-credentials}

1. From **Overview**, open **Settings**.
2. Under **Authentication**, click **Configure Manually**, or **Use Discovered**
when offered.
3. If the issuer is not already known, enter `https://mcp.slack.com` as the
**Issuer URL**. Under **Endpoints**, click **Discover**.
4. In **Attach Remote Identity Provider**, set **Client Type** to **Manual**.
5. Paste the [Slack Client ID](external.md#copy-client-credentials) into **Client ID**.
6. Paste the [Slack Client Secret](external.md#copy-client-credentials) into
**Client Secret (optional)**. Slack requires this secret.
7. Set the token-endpoint authentication method to `client_secret_post` using
the authentication-method control. Do not use `client_secret_basic`.
8. Configure the scopes to match your [Slack user permissions](external.md#set-user-permissions):
`channels:read`, `groups:read`, `im:read`, and `mpim:read` for listing channels.
If an issuer-level scope override is configured, make it match this selection.
9. Click **Attach Identity Provider**.
10. Confirm that the sheet's **Redirect URI** matches
`{{ gram.oauth.callback_url }}`, registered under Slack's
[Redirect URLs](external.md#register-callback).

Slack's discovered authorization endpoint is
`https://slack.com/oauth/v2_user/authorize` and its token endpoint is
`https://slack.com/api/oauth.v2.user.access`. Use these user-token endpoints,
not the bot-token OAuth endpoints. Slack does not support Dynamic Client
Registration. Each user must complete Slack consent when connecting; attaching
the client credentials does not grant access to everyone's Slack data.

If your deployment does not expose the authentication-method or scope controls,
ask the Control Plane administrator to configure these values before connecting.
This configuration is based on Slack's documentation and the Control Plane's
OAuth implementation; it has not been tested end to end with a Slack workspace.
From **Overview**, open **Settings**.

Under **Authentication**, if unconfigured, select **Use Discovered** when available; otherwise select **Configure Manually**. If configured but no provider is attached, use **Connected services > Add provider**. If the intended provider is already attached, use its existing controls and skip the provider/client creation and attachment steps below; do not add a duplicate.

#### Select the identity provider

In **Attach Remote Identity Provider**, **Identity Provider** defaults to **Select existing** when project issuers are available. Select the matching provider and skip the new-provider fields below. Otherwise choose **Add new** (or use the new-provider form shown when none exist).

For a new provider only:

1. Enter `https://mcp.slack.com` as the **Issuer URL** if it is not already populated, and keep the auto-derived **Slug**.
1. Under **Endpoints**, wait for automatic discovery. After typing or changing the **Issuer URL**, click **Discover** only if offered.
1. Confirm the discovered endpoints are Slack's user-token endpoints, not the bot-token OAuth endpoints. If discovery does not populate them, enter:

Authorization endpoint:

```text
https://slack.com/oauth/v2_user/authorize
```

Token endpoint:

```text
https://slack.com/api/oauth.v2.user.access
```

#### Select the session client

Under **Session Client**, choose **Select existing** only for a client whose saved credentials, scopes, and audience match the requirements below; otherwise choose **Add new**. When reusing a matching client, skip directly to **Verify the callback and attach** below. Do not create credentials or register the client again. Otherwise choose **Add new** (or use the new-client form shown when no clients exist) and complete these new-client-only steps:

1. Set **Client Type** to **Manual**. Slack does not support Dynamic Client Registration.
1. Paste the [Slack Client ID](external.md#copy-client-credentials) into **Client ID**.
1. Paste the [Slack Client Secret](external.md#copy-client-credentials) into **Client Secret (optional)**. Slack requires this secret.
1. Set **Token Endpoint Auth Method** to `client_secret_post`. Do not use `client_secret_basic`.
1. In **Scope (override)**, enter the scopes that match your [Slack user permissions](external.md#set-user-permissions), comma-separated: `channels:read`, `groups:read`, `im:read`, and `mpim:read` for listing channels. If an issuer-level scope override is configured, make it match this selection.

#### Verify the callback and attach

1. Confirm that the callback URL registered under Slack's [Redirect URLs](external.md#register-callback) is `{{ gram.oauth.callback_url }}`. For a new manual client, also compare it with the sheet's displayed **Redirect URI**. The existing-client selection does not display that field; check the registered callback in the provider's app settings instead.
2. Click **Attach Identity Provider**.

Each user must complete Slack consent when connecting; attaching the client credentials does not grant access to everyone's Slack data.

If your deployment does not expose the authentication-method or scope controls, ask the Control Plane administrator to configure these values before connecting. This configuration is based on Slack's documentation and the Control Plane's OAuth implementation; it has not been tested end to end with a Slack workspace.

<!-- verify(operator): the template key substitutes this same Redirect URI value -->
<!-- screenshot: Attach Remote Identity Provider with Manual selected, user-token endpoints and client_secret_post configured, and credentials redacted -->
Expand Down
Loading