DocuSOR

DocuSOR Documentation

DocuSOR gives coding agents shared, verified context and memory about your codebase: its services, ports, routes, environment variables, and how to run it. The same context is served to every agent and every engineer in your organization, whichever MCP-capable tool or model they use. It writes that context when you connect a repository, proves it against your running app in an isolated cloud sandbox, and re-checks it as your code changes. Agents read it through the DocuSOR MCP server instead of re-exploring the repo.

How DocuSOR works

  1. Onboarding writes a baseline. When you connect a repository, DocuSOR scans it for services, ports, routes, configuration, and how the app boots, and turns what it finds into checks.
  2. Every fact is proven. DocuSOR runs those checks against your app in an isolated sandbox. By default, agents are only served facts whose checks passed.
  3. Agents read it. Coding agents call the DocuSOR MCP server and get the verified context in one call.
  4. Agents add to it. When an agent learns something new, it writes it back to DocuSOR with a check. A passing run makes it part of the verified context for every other agent.
  5. It stays current. DocuSOR re-validates each repository on a schedule (daily by default). If the latest run fails or drift is detected, served context is marked stale.

Getting started

  1. Sign in with GitHub, or with your company's SSO on Enterprise. Sign-in only identifies you. It gives DocuSOR no access to your code.
  2. Connect your repositories. Install the DocuSOR GitHub App and choose the repositories you want covered, or, on Enterprise, connect a GitLab instance (cloud or self-managed). See Repository access.
  3. Wait for onboarding. DocuSOR writes and validates a baseline for each repository automatically. Onboarding is free and you don't add anything to your repository.
  4. Connect your coding agent to the DocuSOR MCP server. See Connect your coding agent.
  5. Optional: add `AGENTS.md`. Download it from Settings and commit it to your repository root. Most coding agents read this file automatically, and it tells them to use DocuSOR.

New organizations get 25 free credits. See Credits and billing.

What your repository needs

DocuSOR needs a way to run your app:

  • With a Compose file (docker-compose.yml or compose.yml), DocuSOR starts the stack and waits for it to be healthy before running checks.
  • Without a Compose file, including Dockerfile-only repositories, DocuSOR does not start your app. A Dockerfile's CMD is not run. Checks on files, commands, and tooling still work. To check endpoints, the context needs a step that starts the app; your agent can add one.

A repository with no Compose file, Dockerfile, or .docusor-cloud.yml is skipped.

Repository access

DocuSOR works with repositories on GitHub and GitLab. Standard plans connect GitHub; Enterprise plans connect both GitHub and GitLab. Either way, it never pushes commits or edits files in your repository, and it does not keep a copy of your code. Code is fetched for each run and the sandbox is destroyed when the run ends. See Security for details.

GitHub

Install the DocuSOR GitHub App. You choose which repositories it can see and can change that list or uninstall it at any time in GitHub under Settings → GitHub Apps.

  • Metadata (read). Required for every GitHub App. Lists the repositories you selected.
  • Contents (read). Reads your code at a specific commit so DocuSOR can run it in the sandbox.

The App has no write permissions. It receives these webhook events: installation and installation repositories (to add or remove repositories) plus push (to react to new commits).

GitLab

GitLab.com and self-managed GitLab are available on Enterprise plans. Owners and admins connect it from Repository sources on the dashboard:

  1. Click Connect GitLab and enter the instance URL (must use https://).
  2. Paste a group access token or service-account token with the read_api and read_repository scopes. Use the api scope instead if you want results posted as commit statuses on merge requests. The token is encrypted at rest.
  3. Optionally enter a group path to import only that group and its subgroups.
  4. To validate automatically, add the webhook URL and secret shown in DocuSOR under Settings → Webhooks in GitLab, with Push events and Merge request events enabled.

Revoke access at any time by revoking the token in GitLab.

Connect your coding agent (MCP setup)

DocuSOR is a remote MCP server using the Streamable HTTP transport.

  • URL: https://connect.docusor.ai/mcp
  • Header: docusor-org-mcp-key: <your key>

Get a key on the Team & Access page. Create a per-engineer key (usage is attributed to that engineer), or, as an org owner, generate the organization key. Keys are shown once. The page can also download a ready-made config for each client below. Keep keys out of committed files and revoke a leaked key on the same page.

Claude Code

claude mcp add --transport http docusor https://connect.docusor.ai/mcp \
  --header "docusor-org-mcp-key: <your key>"

Or in .mcp.json:

{
  "mcpServers": {
    "docusor": {
      "type": "http",
      "url": "https://connect.docusor.ai/mcp",
      "headers": { "docusor-org-mcp-key": "<your key>" }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "docusor": {
      "url": "https://connect.docusor.ai/mcp",
      "headers": { "docusor-org-mcp-key": "<your key>" }
    }
  }
}

VS Code / GitHub Copilot (.vscode/mcp.json)

{
  "servers": {
    "docusor": {
      "type": "http",
      "url": "https://connect.docusor.ai/mcp",
      "headers": { "docusor-org-mcp-key": "<your key>" }
    }
  }
}

Windsurf (mcp_config.json)

{
  "mcpServers": {
    "docusor": {
      "serverUrl": "https://connect.docusor.ai/mcp",
      "headers": { "docusor-org-mcp-key": "<your key>" }
    }
  }
}

To test the connection, ask your agent to "list my DocuSOR repos". It should call list_repos.

Working with your coding agent

The MCP server explains its own workflow to the agent when it connects, and getting_started returns the full tool map. The main tools:

  • Read: query_context answers a targeted question with only the matching verified facts. get_repo_context returns a repository's full verified context.
  • Write: audit_repo lists what is not yet documented or proven. put_repo_context writes new context and its checks as a draft. validate_repo runs the checks; a passing run promotes the draft to verified context. get_run_report shows why a run failed.
  • Check code changes: validate_changes runs your uncommitted edits (up to 50 files, 1 MB) against the existing verified context before you commit.
  • Across repositories: get_dependency_graph and blast_radius show which services depend on each other and what would break if a contract changes.
  • Docs: check_doc tests one of your repository's Markdown files. See Writing testable docs.

Context lives in DocuSOR, not in your repository. Agents should not edit README.md to satisfy DocuSOR.

Testing your docs

DocuSOR can also test your repository's own Markdown files, such as README.md and runbooks. Write checkable facts as short claims (for example, "GET /health returns 200"), then click Test a doc on the repository page. DocuSOR reports each claim as passed or failed. See Writing testable docs.

Credits and billing

Standard is pay-as-you-go with prepaid credits. One credit costs $0.10, or as little as $0.08 with larger packs. New organizations get 25 free credits.

1 credit per read:

  • get_repo_context and query_context
  • get_dependency_graph and blast_radius
  • check_contract_drift, get_shared_contract, list_contract_consumers, and list_upstream_changes

1 credit per run an agent starts: validate_repo, validate_changes, and check_doc. The credit is refunded if the run never executes.

Free:

  • Onboarding, scheduled re-validation, and runs triggered by commits
  • Runs and doc tests started from the dashboard
  • list_repos, search_repos, get_repo_validation_status, audit_repo, put_repo_context, get_pending_changes, get_run_status, get_run_report, ack_upstream_changes, getting_started, and how_to_write_context

At zero balance, paid reads and agent-started runs stop until you buy more credits on the Billing page. Free operations keep working.

Enterprise

Enterprise is an annual platform fee plus prepaid credits, with unlimited repositories and seats. It adds:

  • GitHub and GitLab. Connect GitLab.com or self-managed GitLab alongside GitHub. See Repository access.
  • SSO. Engineers sign in with your identity provider over SAML or OIDC.
  • Teams. Owners and admins group repositories into teams and choose who can see each one.
  • Self-hosting. Run DocuSOR in your own infrastructure, including air-gapped environments, so code and context stay on your network.
  • Private runners. Dedicated validation runners for your organization (add-on).
  • Audit logs and advanced support.

To talk about Enterprise, use Contact sales on the pricing section.

Getting help

See the FAQ. For security questions, email [email protected].