For developers & AI agents

Ops updates the spec. Your agent pulls the approved one.

The people who own a spec sign it off in VersoDocs. Developers, CI and AI agents read that Current version over MCP, the CLI or the REST API. Never a draft.

Start freeSee the workflow
Reference

Developer reference

Connect an agent, script the CLI or call the API.

Developer docs →

Guides and reference for the MCP server, CLI, GitHub workflows and REST API.

OpenAPI spec →

The REST API (v1) as OpenAPI. Import into Postman or generate a client.

The problem

Your agent is only as good as the spec it reads.

Agents build fast from whatever they’re handed. Hand them a stale copy or a half-edited wiki page and they build the wrong thing, fast.

Stale copies in the repo

Someone pasted the spec into docs/ months ago. It has changed twice since, and the repo doesn’t know.

Drafts read as decisions

An agent pointed at a live wiki page reads the half-finished edit nobody approved.

No signal when it moves

The spec changes in a meeting. The PR built on last week’s version still ships.

How it works

From a spec change to the code that implements it.

Everything downstream picks up the approved version, and only that.

  1. v12 · CURRENT

    The repo is built from v12.

    docs/specs/checkout-api.md was written by npx @versodocs/cli pull, and versodocs.lock records that it is v12.

  2. PROPOSAL

    Ops proposes a change.

    The ops lead updates the retry policy in a proposal and engineering reviews the diff. Agents, the API and the repo still see v12.

  3. v13 · CURRENT

    v13 is approved and published.

    The GitHub auto-sync workflow opens “Update specs from VersoDocs” with v12 → v13. Slack or Teams hears about it too.

  4. AGENT

    The developer’s agent implements it.

    “Pull the approved Checkout spec and implement the new retry policy.” The agent reads v13 over MCP and, on Team, asks what changed since v12.

  5. CI

    Outdated PRs get caught.

    A pull request that still references v12 fails the GitHub spec check (Team) before it merges.

~/checkout-service
# Pull the approved spec into the repo
$ npx @versodocs/cli pull eng/specs/checkout-api
✓ docs/specs/checkout-api.md  v13 · Current

# In CI: fail when a spec has moved on
$ npx @versodocs/cli check
docs/specs/payments.md      v4  v4   up to date
docs/specs/checkout-api.md  v12 v13  outdated

# Or ask your agent (MCP)
› pull the approved Checkout spec and implement §3
✓ get_doc checkout-api v13 · Current
What you get

The approved spec, everywhere code is written.

Four ways in. All of them return published versions only.

Remote MCP server

Connect Claude Code, Cursor, VS Code / Copilot or Claude Desktop in one click (OAuth) or with an API key. Every member connects their own. Reading Current is on every plan; Team adds search, the doc tree, history and diffs.

CLI with a lockfile

npx @versodocs/cli pull writes Markdown with version front-matter. status and check compare the repo to Current; diff shows what changed (Team). versodocs.lock diffs cleanly in PRs.

GitHub auto-sync

A ready-made workflow runs hourly and opens a PR when a spec has a new version. Nothing changes until someone merges. Every plan.

GitHub spec check

Paste a spec reference into a PR. The check fails once that version is no longer Current, with a link to what changed. Team and Pro.

REST API

Read Current docs on every plan. Team adds history, diffs, search, the workspace tree and attachments.

Agents propose, humans approve

On Team, agents connected in one click can open proposals (25 a month per organization). Pro makes it unlimited and lets API keys propose too. Agents can never publish.

Keys you control

Free: 1 key at 30 requests/min. Team: 5 keys at 120/min. Pro: 20 keys at 600/min, workspace-scoped keys and an API audit log.

Webhooks

Post proposals, verdicts and new versions to Slack or Microsoft Teams on every plan. Team and Pro add signed JSON webhooks and every event.

Questions

Good to know.

Which AI tools can connect?
Any MCP client. We document setup for Claude Code, Cursor, VS Code / GitHub Copilot and Claude Desktop. Connect with one click (OAuth) or paste an API key.
Does an admin have to set up each developer’s agent?
No. Any member connects (and disconnects) their own agent from Personal settings. Admins manage API keys for CI and scripts in Developer settings.
Can an agent change a spec?
Only through a proposal, and only on Team or Pro. The agent acts as the member who connected it, so it needs edit rights. Your reviewers approve or reject; nothing an agent does goes live on its own.
Do drafts ever leave VersoDocs?
No. The API, CLI and MCP server only return published versions.
What works on the Free plan?
Reading Current docs over the API, CLI and MCP, cli pull / status / check, and GitHub auto-sync. Everything else above is marked Team or Pro.
Do I need to install anything?
No. The MCP server is remote, and the CLI runs with npx. The GitHub workflow is one YAML file you copy into .github/workflows.
Keep reading

More on VersoDocs.

Technical specs →

One approved version of every spec, reviewed by engineering and approved by product before anyone builds from it.

SOPs & procedures →

Controlled SOPs with approval before publish, proof of which version was in force, and read-and-acknowledge.

VersoDocs vs Google Docs →

Real-time co-writing vs one approved version: when to use each, and how teams use both.

VersoDocs vs Notion →

A flexible workspace vs controlled publishing for the documents that need one approved version.

VersoDocs vs Confluence →

A team wiki with approval add-ons vs approval built into the only way a document changes.

Point your agent at the approved spec.

Free for two people. Publish one spec, run npx @versodocs/cli pull, and connect your agent.

Start freeSee pricing