Slack

Cosmo's Slack integration connects to Slack's official hosted MCP server (mcp.slack.com) — the same pattern as Atlassian and Pylon. There is no binary to install. Each user authorizes with their own Slack account, so the AI accesses only what that user can see.

How it works

Desktop / CLI
  └── RemoteOAuthProvider (staticClientId + staticClientSecret)
        └── StreamableHTTPClientTransport
              └── https://mcp.slack.com/mcp   ← Slack-hosted MCP server

Tokens are stored on each user's device (~/.cosmo/mcp-tokens/<instanceId>.json). A copy is also saved to that user's own connector record on the Cosmo server, so their routines can use Slack while the desktop app is closed. Tokens are never shared between users.

Unlike Atlassian (which supports Dynamic Client Registration), Slack requires a registered Slack App with a fixed Client ID and Client Secret. These are stored on the Cosmo server at seed time and passed to the OAuth flow as static credentials.

What Cosmo can do

Slack's hosted server defines these tools and their exact names, and can add more over time. Cosmo uses whatever tools your connection offers.

Prerequisites (self-hosted setup)

1 — Create a Slack App

1. Go to api.slack.com/apps → Create New App → From scratch.
2. Name the app (e.g., Cosmo) and select your workspace.
3. The app must be an internal app or directory-published app — Slack does not permit unlisted distributed apps to use the MCP server.

2 — Add user token scopes

Under OAuth & Permissions → Scopes → User Token Scopes (not bot token scopes), add:

search:read.public, search:read.private, search:read.mpim, search:read.im, search:read.files, search:read.users, channels:history, channels:read, groups:history, groups:read, im:history, im:read, mpim:history, mpim:read, chat:write, users:read, users:read.email, canvases:read, canvases:write

canvases:read is what lets Cosmo read and save canvases. Without it, those requests fail with a message telling you to add it.

3 — Register the redirect URL

Under OAuth & Permissions → Redirect URLs, add the callback URL that matches your environment. The desktop app uses a local callback server — register http://localhost (Slack allows wildcard ports for localhost).

4 — Set server environment variables

COSMO_SLACK_CLIENT_ID=your-slack-app-client-id
COSMO_SLACK_CLIENT_SECRET=your-slack-app-client-secret

5 — Seed the provider

pnpm -C packages/server seed:providers

This registers Slack in the ConnectorProvider table with authMode: REMOTE_OAUTH and mcpUrl: https://mcp.slack.com/mcp. The seed is idempotent — safe to re-run.

Setup: two steps

Slack uses the same two-step gate as Microsoft 365: an org admin connects first to bind the workspace, then each member connects individually.

Step 1 — Admin connects (one time, per organization)

A Cosmo org OWNER or ADMIN must connect Slack first. This binds your organization to a specific Slack workspace (team_id). After this, no one — inside or outside your org — can attach a different Slack workspace to your Cosmo org.

1. Open Cosmo Desktop → Integrations.
2. Find Slack and click Connect.
3. Enter a label (e.g., Company HQ).
4. A browser window opens to Slack's OAuth screen. Sign in with your Slack account and click Allow.
5. Cosmo records the workspace binding. Other members can now connect.

If you are not an org OWNER or ADMIN, you will see an error asking you to ask an admin to connect first.

Step 2 — Each member connects (once per member)

Once the admin binding is in place, every member connects individually:

1. Open Cosmo Desktop → Integrations.
2. Find Slack and click Connect.
3. Enter a label (e.g., Work).
4. Sign in with your own Slack account. Cosmo verifies your account belongs to the bound workspace.
5. Your personal tokens are stored locally — no teammate can read your messages.

CLI

cosmo mcp connect slack --label "Work"

Or inside an active cosmo session:

/mcp connect slack "Work"

Managing connections

cosmo mcp list
cosmo mcp remove <instance-id>

Saving a Slack canvas to Cosmo

A Slack canvas can be kept in Cosmo as a workspace document, so it stays part of your workspace's context: later chats, searches and routines can find it without going back to Slack.

Save a canvas. In a chat, ask Cosmo to save it and name or link the canvas:

Save the "Q4 roadmap" Slack canvas to this workspace.
Sync https://acme.slack.com/docs/T0123ABC/F07ABC1234 into the Marketing workspace.

If you name the canvas instead of linking it, Cosmo looks it up in Slack first. The canvas is read with your Slack account, so you can only save canvases you can open in Slack. It is stored as a document in the workspace you choose (the one you're in, unless you name another), titled with the canvas's own heading.

Keep it up to date. A saved canvas shows Copy of Slack canvas … · last synced … above it. Click Re-sync there, or ask Cosmo to re-sync the canvas. This updates the same document, never a second copy, and keeps any new title you gave it. To refresh a canvas on a schedule, create a routine that asks Cosmo to re-sync it.

What to expect:

• It's a copy, and it only goes one way. Nothing is written back to Slack, and any edits you make to the document in Cosmo are replaced on the next sync.
• Only the person who saved it can re-sync it. Anyone else in the workspace can read the copy, but Re-sync is only offered to whoever saved it.
• Very large canvases are cut. Over about 1 MB, only the beginning is kept, and the document says so at the top.
• Formatting comes from Slack's export. The document is the markdown Slack exports for the canvas, so embedded files, unfurls and some formatting may not carry over. Images appear as links you can open, rather than loading inside Cosmo.

Credential storage

OAuth tokens are stored locally on the user's device:

~/.cosmo/mcp-tokens/<instanceId>.json

A copy is also saved to that user's own connector record on the Cosmo server, so their routines can use Slack while the desktop app is closed.

Each user's tokens are isolated to their own Slack account. One user's session cannot read another's messages.

Revoking access

• From Cosmo: click Disconnect next to Slack in the Integrations screen, or run cosmo mcp remove <instance-id>. The local token file is deleted immediately.
• From Slack: go to Settings & administration → Manage apps, find Cosmo, and click Remove. Existing tokens will fail on next use.

Troubleshooting

"not_allowed_token_type" from Slack. You added scopes under Bot Token Scopes instead of User Token Scopes. Slack's MCP server requires user tokens. Move all scopes to User Token Scopes, reinstall the app, then reconnect.

"invalid_client_id" or OAuth fails to start. Verify COSMO_SLACK_CLIENT_ID matches the Client ID in Basic Information → App Credentials and that pnpm seed:providers was re-run after setting the env var.

"redirect_uri_mismatch" from Slack. The redirect URL used during the flow is not registered in your Slack App. Add it under OAuth & Permissions → Redirect URLs.

"missing_scope" when using a tool. Add the missing scope under User Token Scopes, reinstall the Slack App to your workspace, then disconnect and reconnect in Cosmo to get a new token with the updated scopes.

"The connected Slack account offers no tool for reading canvases." Slack only offers the canvas tools when the app has the canvases:read user scope. Add it under User Token Scopes, reinstall the Slack App, then disconnect and reconnect Slack in Cosmo. The message lists the tools your connection does offer, which helps support see what Slack returned.

"Only the person who first saved it can re-sync it." A saved canvas copy can only be refreshed by whoever saved it. Ask them to re-sync it, or save the canvas again to make your own copy.

Private channels are missing. Slack's MCP server only surfaces data the authorizing user can access. The user must be a member of the private channel.

OAuth flow times out. The flow must complete within 2 minutes. If the browser window doesn't open, check that Cosmo is allowed to open external URLs in your OS settings.