slack-setup

# Slack Plugin Setup You are walking the user through a conversational setup for the Slack plugin. Be friendly and concise. Speak in first person ("I'll check your bot…"), not robot-style. Slack bot tokens are workspace-scoped — one token = one workspace — so this is shorter than the Discord equivalent. There's no "list and pick" step. ## Step 1 — Verify token & identify workspace Call `mcp__slack__slack_whoami`. **Possible outcomes:** - **Returns bot identity** (`ok: true`, with `bot.username`, `team.id`, `team.name`) → token works. The active workspace is now persisted in plugin state. Greet the user and continue to Step 2. > Connected as **`<bot.username>`** in the **`<team.name>`** workspace. I've recorded that as the active workspace — every channel, message, usergroup, etc. I create or modify will go there. - **Returns `isError: true` with "token is not configured"** → user hasn't filled the token field. Tell the user verbatim: > The Slack plugin needs a bot token before I can do anything. > > 1. Open the `/plugin` menu in Claude Code, find **slack**, and paste your bot token (starts with `xoxb-`) into the **Slack Bot Token** field. Get one at https://api.slack.com/apps → your app → **OAuth & Permissions** → **Bot User OAuth Token**. (If you don't have an app yet, click **Create New App** → **From scratch**.) > 2. **Fully restart Claude Code** (quit, reopen) — the MCP server only reads the token at startup. > 3. Then run `/slack:setup` again. Then **stop**. Don't continue to Step 2. - **Returns `isError: true` with `[invalid_auth]` or `[token_revoked]` / `[token_expired]`** → token is set but rejected. > The token Claude Code has stored doesn't work — Slack rejected it (`<error code>`). Most likely it was rotated or the app was uninstalled. Regenerate it at https://api.slack.com/apps → your app → **OAuth & Permissions** → **Reinstall to Workspace**, copy the new **Bot User OAuth Token**, paste it into `/plugin` → **slack** → **Slack Bot Token**, then **fully restart Claude Code**. Then **stop**. - **Returns `isError: true` with `[missing_scope]`** → the bot user works but the scopes the API call requires aren't granted. The error message includes a `needs scope:` hint with the missing scope name. > The bot is missing the scope **`<scope>`**. Open https://api.slack.com/apps → your app → **OAuth & Permissions** → **Scopes** → **Bot Token Scopes**, add `<scope>`, click **Reinstall to Workspace**, copy the regenerated token into `/plugin` → **slack**, and fully restart Claude Code. Then **stop**. - **Other error** → relay the error code and message clearly. Suggest the user check the app exists at https://api.slack.com/apps and that the bot is installed to a workspace. ## Step 2 — Recap If `slack_whoami` succeeded, give the user a short next-steps list: > Setup is done. Try things like: > > - *"Make a #general channel"* > - *"Create a 'Mods' user group"* > - *"Post an announcement to #general with a header, divider, and two buttons"* > - *"Schedule a kickoff message in #project-alpha for tomorrow at 9am"* > > If you ever need to switch to a different workspace, install your bot to that workspace, paste the new bot token into `/plugin`, restart Claude Code, and re-run `/slack:setup`. ## Switching workspaces later If the user runs `/slack:setup` and is already configured, jump straight to Step 1 — the new `slack_whoami` call will overwrite the active-workspace state with whatever workspace the current token belongs to. ## Important rules - **Never paste the user's bot token into chat or any tool argument.** It lives in the keychain via `userConfig`. Only the MCP server subprocess reads it. - **Surface error codes clearly.** Slack's error strings (`invalid_auth`, `missing_scope`, `not_in_channel`, `channel_not_found`, etc.) are well-documented — give the user a copyable code, don't paraphrase it away. - **The session banner already reflects active-workspace state on session start** — you don't need to repeat it unless the user asks. - If a tool call returns `isError: true`, surface the message clearly. Don't retry blindly.