Slack
Connect Slack to post, edit, and schedule messages, and manage channels, users, reactions, files, and search.
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.
- Setup time
- 8 min
- Auth
- API credentials
- API base URL
- https://slack.com/api
- Rate limits
- Per-method tiers of roughly 1, 20, 50 or 100+ requests per minute. chat.postMessage is about one message per second per channel, and conversations.history and conversations.replies drop to 1 request per minute returning at most 15 objects for apps distributed outside the Slack Marketplace, effective 29 May 2025. Internal workspace apps keep the 50+/min, 1000-object tier.
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
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.
Your Apps
Apps you have built or been added to as a collaborator.
| App Name | Workspace | Distribution | Created |
|---|---|---|---|
| Acme Standup BotA04KJ****K2 | Acme HQ | Not distributed | Mar 4, 2026 |
| Deploy NotifierA02RQ****9L | Acme HQ | Not distributed | Nov 11, 2025 |
Leave the app undistributed. Internal workspace apps keep the higher API rate-limit tiers.
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.
Scopes
A Slack app's capabilities and permissions are governed by the scopes it requests.
| OAuth Scope | Description | Status |
|---|---|---|
| chat:write | Send messages as @PopMCP | Added |
| channels:read | View basic information about public channels | Added |
| channels:history | View messages in public channels @PopMCP is in | Added |
| users:read | View people in the workspace | Added |
| files:read | View files shared in channels @PopMCP is in | Pending install |
Bot Token Scopes sits above User Token Scopes on the same page. Do not mix them up.
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.
Install the app to your workspace
Under Settings, open Install App and click Install to Workspace. Review the consent screen and click Allow.
OAuth Tokens
Install this app to generate the tokens it needs to call the Slack API.
- Workspace
- Acme HQ
- Bot user
- @PopMCP
- Bot Token Scopes
- 5 granted
- User Token Scopes
- 1 granted
Change a scope and you must return here and reinstall, or the new scope is not on the token.
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.
OAuth Tokens for Your Workspace
These tokens were automatically generated when you installed the app to your team.
Reinstalling the app mints a new xoxb- token and invalidates the old one.
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.
Connect in PopMCP
Open your workspace, choose Slack in the marketplace, and fill in the connect dialog:
| Field | What to enter |
|---|---|
| Bot User OAuth Tokensecret | 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.Encrypted with AES-256-GCM on save and never shown again. |
| User OAuth Token (optional)secret | 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-).Encrypted with AES-256-GCM on save and never shown again. |
PopMCP verifies the credential against Slack immediately. On success the connection flips to Verified and its MCP tools are provisioned.
Verify it worked
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
Why: 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
Why: 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
Why: 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
Why: 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
Why: 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
Why: 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.