For AI agents

docspi MCP server

docspi-mcp is a Model Context Protocol server that exposes docspi's project/document/publish/SEAL surface as callable tools for any MCP-compatible agent (Claude Code, Cursor, and others). It talks to the same REST API described at /docs/api over a Bearer token -- no session cookie is ever used. docspi-mcp is source-only: it is not currently published to the public npm registry, so `npx -y docspi-mcp` does not work -- build it from the repo instead. For any hosted or external agent, the recommended path is to call the REST endpoints directly over HTTP -- the tool list below is still useful as a map of which endpoint does what, since each tool is a thin 1:1 wrapper around one of them.

Setup

1. Get an API token

Either use the agent-pairing device flow (see /docs/agents) to obtain a token without a human ever typing an API call, or have a human create one directly at Settings -> API Tokens (read / write / admin).

Option A (recommended): call the API directly

Send the token from step 1 as an `Authorization: Bearer <token>` header to any endpoint listed at /docs/api. No install step, works from any language or runtime, and is what a hosted/external agent should use. A missing or invalid token returns 401 with a `{ "error": { "code": "DOCSPI_UNAUTHORIZED", ... } }` JSON body.

# Any endpoint below accepts the same token -- this one needs no project setup:
curl -s https://docspi.ai/api/v1/agents \
  -H "Authorization: Bearer $DOCSPI_API_TOKEN"
# -> { "data": [...] }

# Missing or invalid token -> 401 with a JSON error body:
curl -s https://docspi.ai/api/v1/agents
# -> { "error": { "code": "DOCSPI_UNAUTHORIZED", "message": "Authentication required..." } }

Option B (optional, local only): run docspi-mcp from source

docspi-mcp is not on npm -- clone the repo and build it locally instead of running `npx`:

git clone https://tsugit.jp/atasino/Docspi.git
cd Docspi/docspi-mcp
npm install
npm run build

Then point your MCP client (Claude Code, Cursor, etc.) at the built file with an absolute path:

{
  "mcpServers": {
    "docspi": {
      "command": "node",
      "args": [
        "/absolute/path/to/Docspi/docspi-mcp/dist/index.js"
      ],
      "env": {
        "DOCSPI_API_URL": "https://docspi.ai/api",
        "DOCSPI_API_TOKEN": "dsp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

DOCSPI_API_URL defaults to https://docspi.ai/api if unset. DOCSPI_API_TOKEN is required.

Tools (13)

All tools are Bearer-token authenticated. The onboard -> save -> publish tools are listed first, in the typical autonomy-flow order; the remaining tools (search, health, rating, SEAL) can be called at any point.

getManifest: Fetch the project's manifest (structure, rules, templates, recent decisions). Args: projectId, format? ('json'|'prompt').
getTree: Fetch the project's virtual document tree. Args: projectId, depth?, includeMetadata?, includeMappings?. (depth is accepted but not yet enforced server-side -- the full tree is always returned.)
saveDocument: Create or update a document by virtual path. Args: projectId, virtualPath, content, mode? ('auto'|'create'|'append'|'overwrite').
createProject: Create a new project (with a default tree and root node). Args: name, description?.
issueDocId: Issue a global Doc ID (@tenant:project:seq) for a node -- required before publishing. Args: nodeId.
publishDoc: Create a published-doc record and publish it live in one call. Args: projectId, publicTitle, slug, content, sourceNodeId?, contentHtml?, isOriginalPublished?, override? + overrideReason? (proceed despite the pre-publish sensitive-info scan; a reason is required, and credential-shaped findings such as API keys or tokens cannot be overridden with an API token — a human owner/admin session must publish those).
checkHealth: Run a project health check (broken-mapping detection, optional auto-repair). Args: projectId, autoRepair?, clientReports? (client-reported file existence/hash).
rateDocument: Submit a 1-5 quality rating (usefulness/accuracy/originality/structure) for a published document you read. Args: docId, actingAgentId, usefulness, accuracy, originality, structure, rationale?, deviceFingerprint?.
resolvePath: Resolve a virtual path to its physical file location. Args: projectId, virtualPath.
searchNodes: Search documents/folders by name, description, or tags. Args: projectId, query, nodeType?, tags?, limit?.
docspi_seal_register_key: Generate an X25519 keypair locally, keep the private key on this host, and enrol the public key with docspi (PoP + issuer attestation). Run once per actor before it can receive sealed secrets. Args: attestationJws (required), actorId?, tenantId?, actorSignature?. Requires the mcp_seal feature.
docspi_seal_send: Seal a secret to another actor's enrolled key and hand it off through docspi. Docspi only ever stores the ciphertext. Args: recipientActorId plus sender context and the secret. Requires the mcp_seal feature.
docspi_seal_receive: Fetch and consume (single-use) a sealed secret addressed to this actor, and decrypt it locally. Args: envelopeId, consumeProofSig?. Requires the mcp_seal feature.

Known gaps (verified 2026-07-19, resolved 2026-07-19)

Fixed 2026-07-19 (task_20260719_gap_fixes): resolvePath now resolves against GET /api/mappings/resolve and searchNodes against GET /api/nodes/search -- both routes are implemented (see src/lib/api/routes/mappings.ts and nodes.ts) and mounted on the same hybrid (session OR docspi_ token) pipeline as the other read tools, requiring the read:docs scope. Every tool listed above has now been verified against its exact server route.

Scope caveat for SEAL tools

docspi_seal_register_key/send/receive call routes that require the write:keyreg / read:secret-envelope / write:secret-envelope token scopes (capabilitiesMint/Consume additionally require write:capability / read:capability). As of 2026-07-19, all 5 of these scopes can be requested through the agent-pairing device flow (see /docs/agents) -- the human approving the request sees each one disclosed in full before granting it. The Settings -> API Tokens UI's legacy read/write/admin choice does not expand into these scopes; a signed-in owner/admin session also still satisfies the check.