# Connect a Slack Agent

> Connect the Slack agent your team already runs to Version Story, so asking for a redline in a channel returns a PDF and a Word file with tracked changes.

This guide connects the Slack agent your team already runs to Version Story,
so a request like "redline these two versions" returns a true tracked-changes
redline — the PDF previewed in the thread, the Word file beside it.

You will need:

- A Slack agent your team operates (see the requirements below)
- A Version Story account (an organization admin, to connect Version Story to your workspace)
- An agent framework with MCP client support

## Agent requirements

**Slack scopes.** Your bot's Slack token needs:

- `channels:history` — read the messages it responds to (add `groups:history`
  / `im:history` for private channels or DMs)
- `chat:write` — post replies
- `files:write` — upload the finished redlines

**MCP client support.** Your framework needs to connect to a remote MCP
server over HTTP, with OAuth handled by the framework (every major MCP SDK
and agent framework with MCP support does both).

**Slack file context in the conversation.** Attached files' `url_private`
links and the event's `team_id` need to reach the model conversation. A bot
that strips attachments down to message text cannot request comparisons.

**Access to tool results.** The bot needs to read the tool results inside
each model response, not just the model's reply text — the redline download
links only appear there, and the bot uploads those files into the thread
itself (Version Story cannot post into your workspace). Frameworks that
surface only the model's final text cannot satisfy this.

**Version Story sign-in.** The account the agent signs in as needs
to belong to the organization that connects the workspace, and the
auth state your framework saves at sign-in needs to persist wherever the
agent runs.

## Connect Version Story to your workspace

This lets Version Story download the private files your team attaches in
Slack, so your agent never has to download or re-upload documents itself.

1. In Version Story, your organization admin opens
   **Organization Settings → Slack Integration → Connect Slack Workspace** and
   approves the install. The **Version Story** app requests one scope,
   `files:read`; it receives no messages and posts nothing.
2. Invite it to each channel whose files it should access —
   `/invite @Version Story`. It can only see files in channels it has been
   added to.

## Connect your agent to Version Story

Your agent calls Version Story's MCP server as a Version Story user; every
comparison it creates is saved in that user's projects.

1. **Choose the account the agent will act as.** Create (or pick) a Version
   Story user in the same organization that connected Slack. A
   dedicated account (for example `agent@yourfirm.com`) keeps agent-created
   projects separate from your team's own.

2. **Add the server to your framework's MCP configuration:**

   ```
   https://mcp-compare.versionstory.com/mcp
   ```

   The server uses standard MCP OAuth. When your framework prompts for
   authorization, sign in in the browser as the account from step 1. Your
   framework stores and refreshes the credentials from then on.

That's the whole integration: the comparison workflow itself is defined by
the server's tools and followed by the model, and your bot's two
responsibilities — passing message context in, uploading the finished files —
are the requirements at the top of this guide.

## Troubleshooting

- **File-access error on a comparison** — the Version Story app is missing
  from that channel; invite it.
- **Reconnect-required error** — the workspace connection was revoked; an
  admin reconnects it in Version Story ([Connect Version Story to your workspace](#connect-version-story-to-your-workspace)).

## Test it

With the agent running, post two versions of a document in the channel and ask
for a redline. Within about a minute the thread should show the redline PDF
previewed inline and the Word tracked-changes file below it. Reply in the
thread as a second test — the bot should answer in the same conversation.

![Finished redline in a Slack thread — summary, PDF preview, and Word file](https://www.versionstory.com/help/slack-agent-setup/09-redline-in-thread.2c30582c.jpg)