MCP server for AI agents

Connect with one click (OAuth)

Recommended for people. Add the URL to your client; on first use it opens VersoDocs in your browser, you sign in, pick the organization and click Allow. No key to copy. Implements the MCP Authorization spec (2025-06-18).

Claude Code

claude mcp add --transport http versodocs https://versodocs.com/api/mcp

1. Run the command in your terminal (add --scope project to share it with your repo).
2. In Claude Code, type /mcp, pick versodocs and choose Authenticate.
3. Your browser opens VersoDocs. Sign in and click Allow.

Cursor

1. Settings → MCP → Add new MCP server → type "Streamable HTTP" (or "url"), URL https://versodocs.com/api/mcp.
2. Click Connect (or Needs login) next to versodocs.
3. Sign in to VersoDocs in the browser window and click Allow.

VS Code / Copilot

1. Command Palette → "MCP: Add Server…" → HTTP → paste https://versodocs.com/api/mcp → name it versodocs.
2. Start the server; VS Code asks to authenticate. Click Allow.
3. Sign in to VersoDocs in the browser and click Allow.

Claude Desktop / claude.ai

1. Settings → Connectors → Add custom connector.
2. Name it VersoDocs and paste https://versodocs.com/api/mcp.
3. Click Connect, sign in to VersoDocs and click Allow.

The consent screen shows which app is asking, an organization picker if you belong to several, what the app can and can't do, your plan's limits, the scopes to grant (on Team: review proposals and propose changes, the latter only if you can edit, 25 agent proposals a month per organization; on Pro also manage docs & folders and publish approved proposals, unchecked by default) and, on Pro, an optional single-workspace limit.

• The app acts as you: it sees only workspaces you can open, and stops working if you leave the org.
• Each connected app (per app, member and org) counts as one key toward the plan's limit (Free 1, Team 5, Pro 20). Reconnecting the same app replaces the old connection.
• Admins see and disconnect apps under Settings → Developer → Connected AI apps.

Connect with an API key

For CI, scripts and clients without OAuth. Use a key from Organization settings → Developer, the same keys as the REST API. The config-file snippets read the key from an environment variable or a secure prompt, so it never lands in a committed file.

Claude Code

Run in your terminal (add --scope project to share with your repo, minus the key)

claude mcp add --transport http versodocs https://versodocs.com/api/mcp --header "Authorization: Bearer vsd_YOUR_KEY"

Cursor

.cursor/mcp.json (set VERSODOCS_API_KEY in your environment)

{
  "mcpServers": {
    "versodocs": {
      "url": "https://versodocs.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:VERSODOCS_API_KEY}"
      }
    }
  }
}

VS Code / Copilot

.vscode/mcp.json (VS Code prompts for the key once and stores it securely)

{
  "inputs": [
    {
      "type": "promptString",
      "id": "versodocs-key",
      "description": "VersoDocs API key",
      "password": true
    }
  ],
  "servers": {
    "versodocs": {
      "type": "http",
      "url": "https://versodocs.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:versodocs-key}"
      }
    }
  }
}

Claude Desktop and claude.ai connect with OAuth only (custom connector), with no mcp-remote bridge or key needed.

Tools

30 tools. tools/list shows a tool only when the credential holds its scope, so an agent never sees write tools it wasn't granted. A held tool outside the org's plan (e.g. Team reads on Free, or after a downgrade) stays listed with a plan note in its description; calling it returns an isError result naming the plan that unlocks it and the upgrade URL.

• path_or_id accepts a document id, the path shown by list_docs, a VersoDocs URL, or a reference versodocs:<org>/<id>@vN. A URL or reference that pins a version (?v=12, @v12) reads that version on Team+; on Free the agent gets Current and a note.
• search_docs is full-text on Team and Pro; on Free it matches titles and paths and says so. Explicit get_doc version needs Team.
• propose_change and update_proposal take the content as content_markdown (the whole document) or edits: [{ find, replace }] applied in order, each find matching exactly once (all or nothing). Prefer edits for small changes to long documents.
• Images and files in proposals: upload_attachment takes the bytes base64-encoded (up to 5.0 MB) and returns a Markdown snippet to paste into content_markdown or an edit. ![alt](https://…) embeds an image by URL; images and attachments already in the document survive as long as their Markdown is kept. Larger files: the REST presigned upload.
• proposal_id accepts the proposal id or its VersoDocs URL. get_proposal returns the diff, reviewers, advisory AI reviews and comment ids (for reply_to / resolve_comment); include_content adds the full text.
• list_document_comments reads the comment threads on a published document (Current, or version; with docs:read), including threads carried forward from older versions with the version each was written on. comment_on_document (a quote from the version, or reply_to) and resolve_document_comment need proposals:review.
• Read tools carry readOnlyHint: true; delete_doc carries destructiveHint: true (every other tool false); every tool has openWorldHint: false.
• What agents may do, the safety rules (advisory verdicts, own proposals only, no e-signatures, guarded deletes) and the REST twin of each tool: Agent workflows.

Example prompts

• “Pull the approved Checkout spec from VersoDocs and implement section 3.”
• “What changed in the Payments API spec since v12? Update the client to match.”
• “Is the spec referenced in this PR description still Current?”
• “Search VersoDocs for our retry policy and follow it in this change.”
• “Cite the spec version you implemented in a code comment.” Agents cite the reference; check_reference and the GitHub spec check later tell you when it moved on.
• Team / Pro: “Draft the API changes we just made back into the Payments spec and propose it for review by lead@acme.com.”
• Team / Pro: “Review the open proposals on the Payments spec against our API style guide; comment inline and leave a verdict.”
• Pro: “Address the review comments on my proposal, update it, and publish it once it’s approved.”
• Pro: “Create an apis/v2 folder in eng and move the v2 specs into it.”

Limits & protocol

• Rate limit: the key's or connected app's plan budget (30 / 120 / 600 req/min), shared with the REST API. A batch is charged one request per tools/call.
• Large documents: tool text is capped at about 60,000 characters. A longer document is truncated with a note and its heading outline, and the agent re-asks with section. Diffs and trees truncate the same way.
• Protocol: MCP 2025-06-18 (also negotiates 2025-03-26 and 2024-11-05). Stateless, JSON responses only (no SSE, no session id). GET → 405. POST one JSON-RPC message or a batch (max 20); notifications → 202. Methods: initialize, ping, tools/list, tools/call.
• CORS is open (*) because auth is a bearer header, never a cookie.

OAuth flow (for client authors)

Standard MCP Authorization: you only need this if you are building an MCP client.

1. POST /api/mcp without a token → 401 with WWW-Authenticate: Bearer resource_metadata="https://versodocs.com/.well-known/oauth-protected-resource".
2. GET /.well-known/oauth-protected-resource (RFC 9728) → resource = https://versodocs.com/api/mcp, authorization_servers = ["https://versodocs.com"].
3. GET /.well-known/oauth-authorization-server (RFC 8414) → authorize /oauth/authorize, token /api/oauth/token, registration /api/oauth/register, revocation /api/oauth/revoke. S256 only, public clients only.
4. POST /api/oauth/register (RFC 7591 dynamic registration) → client_id. Public clients (token_endpoint_auth_method: none); redirect URIs must be https, loopback http (localhost, 127.0.0.1, [::1], any port) or an app scheme such as cursor://. Throttled per IP.
5. Browser → /oauth/authorize with response_type=code, client_id, redirect_uri, code_challenge, code_challenge_method=S256, state, resource=https://versodocs.com/api/mcp and optional scope → sign in → consent → redirect with code, state, iss (deny → error=access_denied).
6. POST /api/oauth/token (form-encoded; JSON accepted) with grant_type=authorization_code, code, redirect_uri, client_id, code_verifier.
7. Call /api/mcp with Authorization: Bearer vsd_at_…. Refresh with grant_type=refresh_token.

{
  "access_token": "vsd_at_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "vsd_rt_…",
  "scope": "docs:read"
}

Scopes (space-separated in scope; omitted = everything the plan allows, narrowed on the consent screen): docs:read (always), proposals:review (Team and Pro), docs:propose (Team and Pro, members with edit rights; on Team capped at 25 agent proposals per organization per calendar month, UTC), docs:write and proposals:publish (Pro, members with edit rights, opt-in). See scopes per plan. Revoke with POST /api/oauth/revoke (RFC 7009).

Security

• Read-only by default. A credential has docs:read unless given more scopes. docs:propose: on Team only one-click connections (acting as their member), 25 agent proposals a month per organization; on Pro API keys too, unlimited. propose_change opens a proposal your reviewers must approve; it never edits Current.
• Reviews are advisory. submit_review verdicts are shown as AI reviews and never count toward required approvals or trigger auto-publish.
• Publishing needs people. publish_proposal (Pro, proposals:publish) only publishes proposals humans approved, never with an override, and is refused when the workspace requires an e-signature. Agents revise or close only their own proposals.
• Guarded deletes. delete_doc (Pro, docs:write) only removes documents with no published version, and needs the exact title in confirm_title.
• Published content only. Drafts and proposals in progress never leave VersoDocs; archived, unpublished and out-of-scope documents read as not found.
• Connected apps act as their member: same workspace visibility, and a member demoted to viewer loses docs:propose, docs:write and proposals:publish immediately. Their comments and actions are labeled with the app name.
• Scope. Free credentials see the org's active workspace only; a Pro workspace-scoped key sees just its workspace, as on the REST API.
• OAuth hardening. PKCE S256 mandatory, state required, exact redirect-URI matching (loopback may change port), only SHA-256 hashes of codes and tokens stored, iss on responses (RFC 9207), consent page cannot be framed. Tokens are never logged.
• Revocation is immediate: revoke a key or disconnect an app in Settings → Developer. Use one key per developer or tool.
• Auditing: on Pro, MCP usage is sampled into the audit log (api.request, endpoint POST /api/mcp), proposals are logged as api.proposal_created, and agent writes (verdicts, edits, publishes, docs & folders) carry the credential that made them.