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
For step-by-step setup in Claude, including the network egress settings that file transfers need, see Claude Connector Setup. For Slack, see 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.
- Stage.
create_comparison,create_merge,create_combine, orcreate_version_historysets up the work and returns an upload manifest. Nothing has been transferred yet; the response status isawaiting_uploads. - Transfer. The agent performs one HTTP
PUTper source file, using the manifest entry'supload_url,authorization, andcontent_type. These are ordinary HTTPS requests the agent makes itself with whatever HTTP client it has. - Wait.
get_redlines,get_merged_document,get_combined_document, orget_version_history_documentblocks server-side until the artifact exists. It returns within about a minute either withreadyor withprocessing— call again with identical arguments to keep waiting. - 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 PUTs |
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.
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 |
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 |
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.