# Slack setup for PopMCP

A Bot User OAuth Token starting with xoxb- from your Slack app's OAuth & Permissions page, plus the User OAuth Token starting with xoxp- if you need search, reminders or admin methods.

- Auth: API credentials
- Setup time: 8 min
- API base URL: https://slack.com/api
- Credentials screen: https://api.slack.com/apps
- Provider docs: https://api.slack.com/methods

## Before you begin

- A Slack workspace you can install apps into, free plans included
- Permission to install apps, since many workspaces route installs through an admin as "Request to Install"
- Nothing paid and no Slack Marketplace review for an internal app

## Get your credentials

### 1. Create a Slack app

Go to api.slack.com/apps and click Create New App. Choose From a manifest if you have a scope list to paste, otherwise From scratch, then name the app `PopMCP` and pick the workspace it will live in.

Screen: https://api.slack.com/apps

### 2. Add Bot Token Scopes

In the sidebar under Features, open OAuth & Permissions and scroll to Scopes. Under Bot Token Scopes, click Add an OAuth Scope once for each permission you want.

### 3. Add User Token Scopes only if you need them

On the same page, use User Token Scopes for the optional `xoxp-` token. Add `search:read` there if you want message and file search, and skip this step otherwise.

### 4. Install the app to your workspace

Under Settings, open Install App and click Install to Workspace. Review the consent screen and click Allow.

### 5. Copy the Bot User OAuth Token

Return to OAuth & Permissions and find the OAuth Tokens for Your Workspace panel. Copy the Bot User OAuth Token starting with `xoxb-` into PopMCP, and copy the User OAuth Token starting with `xoxp-` into the optional second field if you added user scopes.

### 6. Invite the bot to the channels it should see

In Slack, type `/invite @PopMCP` in every channel PopMCP should reach. Do this for private channels too, since the bot must be a member to read them.

## Fields PopMCP asks for

- Bot User OAuth Token (botToken) [required]: At api.slack.com/apps create an app (Create New App → From a manifest is fastest; paste a manifest that lists the bot scopes you want), Install to Workspace, then under OAuth & Permissions copy the "Bot User OAuth Token" (starts with xoxb-). It's sent as Authorization: Bearer and stored encrypted; used server-side only.
- User OAuth Token (optional) (userToken): Optional. Only needed for user-only methods: message/file SEARCH, reminders, Do-Not-Disturb writes, setting your own presence/profile/status, and the admin.* Enterprise-Grid org-management methods (use an org-admin's token). Add the matching User Token Scopes to your app first (e.g. search:read). Copy the "User OAuth Token" (starts with xoxp-).

## Verify

PopMCP shows Slack as Connected and names your workspace, and a channel-listing tool call returns the real channels the bot can see.

## Troubleshooting

### invalid_auth or not_authed

Cause: The token was truncated, pasted with whitespace, or the app was reinstalled so the old xoxb- was revoked.

Fix: Re-copy the current Bot User OAuth Token from OAuth & Permissions and save it again in PopMCP.

### missing_scope

Cause: A scope was ticked in the config but the app was never reinstalled, so the live token predates the change.

Fix: Add the scope, then open Settings then Install App then Reinstall to Workspace, then paste the newly issued token.

### not_in_channel or channel_not_found on a channel that exists

Cause: The bot user is not a member of that channel, or the channel is private.

Fix: Run /invite @PopMCP in the channel and retry.

### search tools fail while posting works

Cause: Search is a user-token-only API. A bot token can never call it.

Fix: Add search:read under User Token Scopes, reinstall, and paste the xoxp- token into PopMCP's optional User OAuth Token field.

### ratelimited on message history, only 15 messages returned

Cause: Since 29 May 2025, conversations.history and conversations.replies are capped at 1 request per minute and 15 objects for apps distributed outside the Slack Marketplace.

Fix: Keep the app internal and undistributed. Custom workspace apps retain the higher tier.

### The install button reads Request to Install

Cause: The workspace routes app installs through an admin for approval.

Fix: Click it, then ask a workspace admin to approve the request before returning for the token.

---

Source: https://www.docs.popmcp.com/docs/integrations/slack/