@agentdoc/mcp

MCP server for AgentDoc — the fastest way for your agent to publish a markdown doc and hand the human a shareable URL.

Gives your agent (Claude Code, Claude Desktop, Cursor, Codex, Zed, Windsurf, VS Code, Cowork, …) read/write access to your AgentDoc: list, read, create, update, publish, share, fork, version, invite collaborators.

Install

Preferred: hosted remote MCP

The fastest path for most clients — no shell, no config file, no Node install. In your MCP client (Claude Desktop, Claude.ai web, Cowork, etc.) open Settings → Connectors → Add custom connector and paste:

https://mcp.agentdoc.com

Claude runs the OAuth flow and agentdoc tools are available immediately. Works identically across Claude.ai web, Desktop, and Cowork's sandbox — and avoids every Node-version / PATH / nvm issue local stdio installs are prone to.

Local stdio install (escape hatch)

Use this if you need the MCP running locally (air-gapped, custom env vars, or a client that doesn't speak remote MCP). Requires Node 18 or newer on your machine.

On first run the server provisions an anonymous API key and caches it at ~/.agentdoc/mcp-key.json. Claim the account later at agentdoc.com/claim to attach an email.

Claude Code:

claude mcp add agentdoc -- npx -y @agentdoc/mcp

Claude Desktop / Cursor / Windsurf / Cowork / Zed — add to your MCP config JSON:

{
  "mcpServers": {
    "agentdoc": {
      "command": "npx",
      "args": ["-y", "@agentdoc/mcp"]
    }
  }
}

VS Code:

code --add-mcp '{"name":"agentdoc","command":"npx","args":["-y","@agentdoc/mcp"]}'

Codex:

codex mcp add agentdoc -- npx -y @agentdoc/mcp

Troubleshooting: fetch is not defined / EBADENGINE warnings

Your npx resolved to a Node <18 install (common with nvm when an older version sits earlier on PATH). Fix with:

nvm install 20
nvm alias default 20

Then fully quit and relaunch your MCP client (Cmd-Q on macOS — a window close is not enough).

Bring your own key

If you already have an AgentDoc account, create a key at agentdoc.com/settings/keys and pass it via env:

{
  "mcpServers": {
    "agentdoc": {
      "command": "npx",
      "args": ["-y", "@agentdoc/mcp"],
      "env": { "AGENTDOC_API_KEY": "ad_sk_..." }
    }
  }
}

Tools

| Tool | What it does | | --- | --- | | agentdocs_list_agentdocs | List all docs in your workspace | | agentdocs_search_agentdocs | Search public docs by keyword | | agentdocs_read_agentdoc | Read a doc's full markdown | | agentdocs_create_agentdoc | Create a new doc. Pass project_slug and tags when inferable; missing projects are created by default. If the markdown exists on disk, pass file_path — don't inline it as content (stdio only; saves tokens). | | agentdocs_update_agentdoc | Update content, title, or description. Same rule — pass file_path when the new content is already a file on disk (stdio only). | | agentdocs_edit_agentdoc | Partial str_replace edit — like a focused diff, not a full rewrite. Pass edits: [{ old_string, new_string, replace_all? }]. Optional expected_sha enables read-modify-write CAS so you don't clobber concurrent edits. | | agentdocs_delete_agentdoc | Archive a doc | | agentdocs_fork_agentdoc | Fork a doc into your workspace | | agentdocs_publish_agentdoc | Publish as a public webpage | | agentdocs_unpublish_agentdoc | Revert a public doc to draft | | agentdocs_share_agentdoc | Get a secret share link (UNLISTED) | | agentdocs_revoke_share | Revoke a previously-shared link | | agentdocs_set_access | Set visibility (PRIVATE, ORG_VISIBLE, UNLISTED, PUBLIC) | | agentdocs_list_versions | List version history | | agentdocs_read_version | Read a specific historical version | | agentdocs_restore_version | Restore to a previous version | | agentdocs_invite_collaborator | Create an invite link | | agentdocs_list_collaborators | List collaborators | | agentdocs_accept_invite | Accept an invite as an agent and get an API key | | agentdocs_list_projects | List projects | | agentdocs_read_project | Read a project and list its docs | | agentdocs_create_project | Create a new project | | agentdocs_assign_doc_to_project | Move a doc into a project | | agentdocs_unassign_doc_from_project | Remove a doc from a project | | agentdocs_list_tags | List popular tags | | agentdocs_list_doc_tags | List tags on a doc | | agentdocs_add_tags_to_doc | Add tags to a doc | | agentdocs_remove_tag_from_doc | Remove a tag from a doc |

Projects and tags

Treat organization as part of creating a doc, not a cleanup step.

Before creating docs for an ongoing initiative, call agentdocs_list_projects. If a relevant project exists, pass project_slug directly to agentdocs_create_agentdoc. If the user clearly names a project/client/feature and no match exists, still pass project_slug; AgentDoc creates the missing private project by default. Set create_project_if_missing: false only when the user explicitly wants to require an existing project.

Add 2-5 concise tags when the topic is inferable. Prefer tags that help retrieval later: document type (runbook, incident, research), system or feature (billing, mcp, api), and workflow (migration, release, onboarding). Avoid vague tags like doc, notes, or misc.

{
  "name": "agentdocs_create_agentdoc",
  "arguments": {
    "title": "Billing Webhook Runbook",
    "content": "# Billing Webhook Runbook\n...",
    "project_slug": "billing-platform",
    "create_project_if_missing": true,
    "tags": ["runbook", "billing", "webhooks"]
  }
}

Uploading a local file (stdio only)

If the markdown already exists on disk, pass file_path — do not read the file into the conversation and inline it as content. On the stdio transport the MCP server runs on your machine, so agentdocs_create_agentdoc and agentdocs_update_agentdoc accept a file_path arg. The server reads the file itself; your model doesn't spend output tokens re-emitting every byte of markdown back out. This is the default calling pattern whenever a local .md exists — treat content as the fallback for text generated in-conversation that isn't on disk.

// Create
{
  "name": "agentdocs_create_agentdoc",
  "arguments": {
    "title": "Deploy Checklist",
    "file_path": "/abs/path/to/deploy-checklist.md"
  }
}

// Update (replaces entire content, like PATCH)
{
  "name": "agentdocs_update_agentdoc",
  "arguments": {
    "slug": "deploy-checklist",
    "file_path": "./deploy-checklist.md",
    "message": "sync from repo"
  }
}

Relative paths resolve against the MCP process's working directory (for stdio launches that's usually the client's workspace root). Files over 2 MB are rejected. The remote transport at mcp.agentdoc.com does not expose file_path — it runs on our infra, not your machine — so remote MCP callers should use the REST endpoint below or send content inline.

Partial edits (str_replace)

For small changes — fix a typo, append to a section, swap a heading — agentdocs_edit_agentdoc is much cheaper than re-emitting the whole doc. Semantics match Claude Code's Edit / MultiEdit tools:

• Each edit replaces old_string with new_string. The match must be exact (whitespace included) and unique in the doc — include enough surrounding context to disambiguate, or pass replace_all: true.
• Edits in the array are applied in order, atomically. If any edit's old_string is missing or ambiguous, nothing is written (HTTP 422, with the failing editIndex in the error details).
• For safety against concurrent edits (a human in the editor, another agent), read first and pass back meta.contentSha as expected_sha. The server returns HTTP 409 if the doc changed in the meantime, and you re-read and retry.

// 1. Read to capture contentSha
{ "name": "agentdocs_read_agentdoc", "arguments": { "slug": "deploy-checklist" } }
// → meta.contentSha = "9f86d0...sha256..."

// 2. Apply a few str_replace edits
{
  "name": "agentdocs_edit_agentdoc",
  "arguments": {
    "slug": "deploy-checklist",
    "edits": [
      { "old_string": "## Steps\n1. Build", "new_string": "## Steps\n1. Lint\n2. Build" },
      { "old_string": "TODO: smoke test",   "new_string": "Smoke tests run via `npm run smoke`" }
    ],
    "expected_sha": "9f86d0...sha256...",
    "message": "expand build steps and link smoke tests"
  }
}

agentdocs_update_agentdoc (full-content replace) is still the right tool when you've regenerated the whole doc; agentdocs_edit_agentdoc is the right tool when you want a focused, reviewable diff.

Bundled skill

This package ships a SKILL.md that teaches agents (Claude Code, Cowork, Claude Desktop, etc.) when to reach for AgentDoc — long-form docs, runbooks, postmortems, research notes — and how (MCP-vs-CLI decision, visibility defaults, anti-patterns). If you install the CLI and run agentdoc install claude-code, it's dropped into ~/.claude/skills/agentdoc/ automatically. Otherwise you can copy it there by hand.

Configuration

| Env var | Default | Description | | --- | --- | --- | | AGENTDOC_API_KEY | (auto-provisioned) | Your API key (ad_sk_...) | | AGENTDOC_API_URL | https://api.agentdoc.com | Override the API host (useful for self-hosting) |

License

MIT