# MCP server overview

> A hosted Model Context Protocol server giving agents the full comparison engine — compare, merge, combine, and version history.

The Version Story MCP server lets an AI agent operate the comparison engine on behalf of a
signed-in user, with the whole engine available as tools: compare, merge, combine, and
version history.

| | |
| --- | --- |
| Endpoint | `https://mcp-compare.versionstory.com/mcp` |
| Transport | Streamable HTTP |
| Auth | OAuth 2.1 with PKCE and dynamic client registration |
| Exposes | Tools only — no resources, no prompts |

## Connecting

Point any compliant MCP client at the endpoint. The client registers itself, walks the user
through sign-in, and discovers the tool schemas — you configure a URL and nothing else.

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

The client also needs network access to Version Story. Agent runtimes that restrict outbound
requests — Claude among them — must have this domain on their allowlist, or the file transfers
in steps 2 and 4 below are blocked:

```
*.versionstory.com
```

For step-by-step setup in Claude, including where that setting lives, see the
[Claude installation guide](/developers/mcp/claude-installation-guide). On the Claude desktop
app and in Cowork, the [Version Story plugin](/developers/plugin/overview) runs the same engine
locally and faster, and needs no allowlist entry at all. For Slack, see
[Slack Agent Setup](/help/slack-agent-setup).

Tool input schemas are part of the protocol: call `tools/list` and you get current JSON
Schema for every tool, always in sync with the deployed server. The pages here document the
**responses** and the workflow, which the protocol does not declare.

## How the work flows

Every creating operation follows the same four steps.

1. **Stage.** `create_comparison`, `create_merge`, `create_combine`, or
   `create_version_history` sets up the work and returns an upload manifest. Nothing has
   been transferred yet; the response status is `awaiting_uploads`.
2. **Transfer.** The agent performs one HTTP `PUT` per source file, using the manifest
   entry's `upload_url`, `authorization`, and `content_type`. These are ordinary HTTPS
   requests the agent makes itself with whatever HTTP client it has.
3. **Wait.** `get_redlines`, `get_merged_document`, `get_combined_document`, or
   `get_version_history_document` blocks server-side until the artifact exists. It returns
   within about a minute either with `ready` or with `processing` — call again with
   identical arguments to keep waiting.
4. **Download.** The ready response carries `download_manifest_url`. Fetch it, then fetch
   the file URLs it lists, saving them as binary.

For documents already reachable at HTTPS URLs, `create_comparison_from_links` collapses
steps 1 and 2 — the server fetches them itself.

### Waiting is server-side

This is the part that differs most from a conventional REST API. The `get_*` tools do not
return immediately for a client to poll on a timer; they hold the connection open and wait,
emitting keepalive progress every five seconds, returning after roughly a minute at most.
A `processing` result means "call me again", not "you polled too early".

Merge, combine, and version history each build on underlying comparisons, so several
`processing` rounds is normal and a few minutes is not a problem.

## Statuses

Every wait tool reports one of four statuses.

| Status | Meaning | What to do |
| --- | --- | --- |
| `ready` | The artifact exists | Fetch `download_manifest_url` |
| `processing` | Still generating | Call again with the same arguments |
| `failed` | Terminal — it will not finish | Read `failure_code` or `errors`; do not retry |
| `awaiting_uploads` | Sources were never transferred | Check `missing_uploads` and complete the `PUT`s |

## The tools

Fifteen tools, grouped by what they do.

### Comparing

| Tool | Purpose |
| --- | --- |
| `create_comparison` | Stage comparisons from local or attached files |
| `create_comparison_from_links` | Stage comparisons from HTTPS URLs — no upload step |
| `get_redlines` | Wait for redlines and return a download manifest |
| `find_prior_version` | Search stored document families for an earlier version by file name |
| `detach_from_prior_versions` | Undo a wrong automatic document-family link |

See [MCP · Compare](/developers/mcp/compare).

### Merging and combining

| Tool | Purpose |
| --- | --- |
| `create_merge` | Merge revisions that share one base document |
| `get_merged_document` | Wait for the merged document |
| `create_combine` | Combine independent drafts with no shared base |
| `get_combined_document` | Wait for the combined document |

See [MCP · Merge & combine](/developers/mcp/merge).

### Version history

| Tool | Purpose |
| --- | --- |
| `create_version_history` | Attribute every surviving change across an ordered chain of versions |
| `get_version_history_document` | Wait for the version history document |

See [MCP · Version history](/developers/mcp/version-history).

### Account and projects

| Tool | Purpose |
| --- | --- |
| `get_instructions` | Return the full connector workflow guide |
| `check_connection` | Report access-token lifetime and refresh capability |
| `list_projects` | List the user's projects, newest first |
| `list_project_comparisons` | List one project's comparisons, newest first |

`list_projects` returns each project's id, name, timestamps, view type, and web URL. A
project's id is its `version_story_id`, which every other tool takes.
`list_project_comparisons` returns document names, timestamps, status, available formats,
redline URLs, and each comparison's `version_mapping_id`.

## Projects

Work is organised into projects. Pass `version_story_name` to create one, or
`version_story_id` to add to an existing project — repeated calls with the same
`version_story_id` build up a project with many comparison groups.

Creating responses carry `version_story_url`, and each comparison carries a `redline_url`.
Both are links a person can open to view tracked changes interactively in the Version Story
app, and they are worth surfacing to the user rather than keeping internal.

## Signed URLs

Upload authorizations, manifest URLs, and download URLs all expire **one hour** after they
are issued. This is rarely a constraint in practice: the wait tools mint fresh download
URLs on every call, so a finished artifact stays reachable indefinitely. If an upload
manifest lapses before the transfers happen, calling the create tool again with the same
`version_story_id` stages fresh ones.

Do not send source documents anywhere other than the manifest's `upload_url` values — those
are the only upload destinations.