MCP integration (Claude Code and Codex)

@takazudo/zudotext-mcp is the official local stdio Model Context Protocol server for one encrypted zudo-text cloud workspace. Claude Code or Codex can call 20 direct document/history/change/asset tools and one optional cloud-agent tool without driving the app UI.

This is the shipped way to edit workspace documents with a local coding agent. It does not restore the retired in-app terminal/PTY or a local workspace directory. There is no public remote MCP endpoint and no per-published-site MCP endpoint.

The server package is public on npm while its source repository remains private. Users do not need repository access or GitHub credentials to install it.

This page is the user workflow: setup, registration, and day-to-day operation. Local Agent Authoring is the design and safety authority. The @takazudo/zudotext-mcp package page is the distribution, configuration, exact-inventory, and release-verification reference. Agent task recipes is the task-shaped companion to this page: what to type for a given job, which tools it should trigger, and the caveat attached to each one.

Install

Choose one setup path. The recommended Settings-generated command installs and registers the server in one pass; do not precede it with the manual global install. Use the manual path when you need to assemble the package, token, and harness registration yourself. Both paths require Node.js 22.19 or newer.

Recommended: run the Settings-generated command

Open Settings → Local AI Agent:

1. Pick Claude Code or Codex.

2. Choose an absolute password-file path (recommended) or the /dev/tty prompt. For a password file, create it yourself with a trusted editor, write only the workspace password, and run chmod 600 /absolute/path/to/workspace-password before continuing. The Settings screen never reads, displays, copies, or stores the password.

3. Leave the encryption-salt override off; it is a debugging escape hatch, not normal configuration.

4. Choose Create token & config.

5. Copy the one-time config before discarding it or closing Settings. Paste it into a trusted local shell and run it as one executable command block. It installs and verifies the exact npm release, registers the selected harness with the generated environment, and ends with mcp list.

The /dev/tty option means the external harness process prompts through its controlling OS shell while keeping stdin available for MCP framing. It does not refer to the retired in-app terminal.

This flow mints a PAT bound to the current workspace with exactly documents:read, documents:write, assets:read, and assets:write. The raw token appears only in the one-time config reveal. Closing or discarding the reveal drops the UI's copy but does not revoke the token; revoke an unused one under Settings → Access Tokens.

Manual: install the npm package

The package is a public npm-registry publication. Replace <VERSION> with the version shown on the package release reference:

ZUDOTEXT_MCP_VERSION="<VERSION>"
npm install --global "@takazudo/zudotext-mcp@${ZUDOTEXT_MCP_VERSION}"
zudotext-mcp --version

The verification command must print the selected version.

Mint a scoped token

For the manual path, create a PAT under Settings → Access Tokens. Its settled least-privilege default is documents:read, documents:write, assets:read, and assets:write. Add agent:invoke only for ask_zudo_agent, or choose mutually exclusive Full access only for compatibility work that truly needs the wider server surface. Bind an MCP PAT to one workspace and set an expiry.

The server API still interprets an omitted scopes field as full for pre-scoped-token compatibility. The current UI does not silently choose that default.

Add it to Claude Code or Codex

If you ran the generated command from Settings → Local AI Agent, registration is already complete and you can skip these manual examples. Use them when you minted a PAT in the generic token screen or are assembling configuration by hand.

Before running either password-file example, create the absolute-path file with a trusted editor, write only the workspace password, and run chmod 600 /absolute/path/to/workspace-password.

claude mcp add zudotext \
  --env ZUDOTEXT_SERVER_URL=https://your-sync-server.example.com \
  --env ZUDOTEXT_PAT=your_personal_access_token \
  --env ZUDOTEXT_WORKSPACE_ID=your-workspace-id \
  --env ZUDOTEXT_WORKSPACE_PASSWORD_FILE=/absolute/path/to/workspace-password \
  -- zudotext-mcp

claude mcp list

The Codex command has the same shape:

codex mcp add zudotext \
  --env ZUDOTEXT_SERVER_URL=https://your-sync-server.example.com \
  --env ZUDOTEXT_PAT=your_personal_access_token \
  --env ZUDOTEXT_WORKSPACE_ID=your-workspace-id \
  --env ZUDOTEXT_WORKSPACE_PASSWORD_FILE=/absolute/path/to/workspace-password \
  -- zudotext-mcp

codex mcp list

Then ask the harness to call list_notes. Installing the official skill gives it the complete safety policy and exact tool inventory.

Configuration reference

If both password variables are set, the inline environment value wins over the file. The password stays in process memory so an expired document key session can be reopened; the process never writes it to disk.

Install the official authoring skill

After completing either setup path, install the behaviorally equivalent policy skill for the harness you use:

# User scope
zudotext-mcp-install-skill --harness claude-code
zudotext-mcp-install-skill --harness codex

# Repository scope; --project requires an absolute path
zudotext-mcp-install-skill --harness claude-code --project "$PWD"
zudotext-mcp-install-skill --harness codex --project "$PWD"

The user destinations are $CLAUDE_CONFIG_DIR/skills/zudotext-authoring/SKILL.md (falling back to ~/.claude/skills/zudotext-authoring/SKILL.md) and $HOME/.agents/skills/zudotext-authoring/SKILL.md. Repository installs use .claude/skills/zudotext-authoring/SKILL.md and .agents/skills/zudotext-authoring/SKILL.md.

After installing a newer npm release, replace and byte-check the skills explicitly:

zudotext-mcp-install-skill --harness claude-code --update
zudotext-mcp-install-skill --harness claude-code --check
zudotext-mcp-install-skill --harness codex --update
zudotext-mcp-install-skill --harness codex --check

Without --update, an existing skill is never overwritten. An owner may edit the installed destructive-confirmation defaults; such an intentional edit makes the byte-exact --check fail, and --update replaces it. Back up and reapply custom policy around an update. Claude Code explicitly invokes /zudotext-authoring; Codex uses $zudotext-authoring or the /skills selector.

Do not install these external-agent skills under .zudotext/skills/. That is the separate flat-file namespace for zudo-text's in-app inline AI.

Tool tour

The registry contains exactly 21 tools.

Documents and changes

what_changed has a process-local implicit cursor. Successful implicit calls advance it, including intermediate pages; explicit afterCursor calls do not. It resets to zero when the MCP process restarts. The cursor is document-only: asset mutations never appear.

One search scans at most 2,000 candidate paths and reads content from at most 240 documents. Scope with prefix; a truncated response is incomplete, not evidence that no later match exists.

Authoring sessions and document history

Call begin_authoring_session before the first document mutation when an undo boundary matters. A checkpoint is not a workspace snapshot. There is no one-call or atomic rollback: the client fetches the manifest, compares its expectedHeadCursor with a fresh explicit walk: call what_changed(afterCursor: 0), keep passing each response's changeCursor as the next afterCursor until hasMore is false, then compare the final cursor. It applies normal restore/delete/noop work and stops on conflict while reporting possible partial progress. A same-fileId old-path restore plus new-path delete is a move-back. HISTORY_COMPACTED remains distinguishable from empty history. The sync server's nightly version-retention job does not touch the changes log or compaction_floor, so it does not change HISTORY_COMPACTED semantics; it only thins unpinned version rows and queues their unreferenced R2 blobs for delayed reclaim.

Versions, checkpoints, summaries, restore manifests, and what_changed cover documents only.

Assets

Asset plaintext bytes and base64 never enter MCP text or structured results. Transfers cross an explicit local-path boundary: confirm the source before an upload and the new destination before a download. Check usage before material uploads; quota or soft lock can reject creation, while an over-quota account may still list and download.

Assets have no versions, checkpoints, history restore, document cursor, or undo. The narrow family deliberately has no move, rename, delete, recursive delete, replace, or delete-and-recreate tool; do not emulate one. Interactive asset moves/renames and document moves do not rewrite Markdown references.

Cloud agent

Direct tools spend zero AI turns. Every admitted ask_zudo_agent call spends one of the user's shared 100 AI turns per UTC day at admission, even if that turn later fails. Assistant-panel and inline-AI calls share the pool. All Automation API routes also share 120 requests per user per minute; cloud-agent internal calls consume that same budget, so avoid bursts and honor typed retry timing. One bounded internal query_kanban call can consume up to 85 of those requests.

Calls without conversationId share one process-local default conversation; passing an id pins a thread. Successful propose_edit activity returns validated editPreviews. A preview is not applied automatically: review its candidate newContent, then use write_note before expiry with baseVersion as expectedVersion and a fresh idempotency key. create_note is the deliberate direct-write exception: it commits a new note create-only and fails if the selected path already exists.

Write conflicts and retries

Whole-document writes use optimistic concurrency. On VERSION_CONFLICT, read the returned current-version details, re-read the document, reconcile with the owner's intent, and use a new precondition. If the payload or precondition changes, use a fresh idempotency key; the old key belongs only to an exact retry of the old fingerprint. A conflict writes nothing.

• write_note, delete_note, and move_note accept an optional key. The MCP client creates one for that request and keeps it across its internal key-session retry. Supply and reuse a stable key when retrying the same MCP-level operation yourself.

• restore_note_version, upload_asset, and create_asset_folder require a caller-stable key. Reuse it only for the exact same payload.

• stash_log avoids overwrites by choosing the next free dated filename. begin_authoring_session and ask_zudo_agent are not idempotent.

The log-stash recipe

stash_log(project, title, content) replaces a machine-local agent-logs/ directory with synced workspace documents. Logs land directly under logs/:

logs/YYYYMMDD-<project>-<title>.md

The project is retained in both the filename and frontmatter. A collision takes the next -2, -3, … suffix and never overwrites an existing document. Pin logs/ as a Note Tray to browse the direct children in the app.

Resource safety

The official skills apply these defaults to direct and cloud-agent-proposed whole-document writes:

• Ordinary notes and archives/ documents are writable.

• Preserve existing YAML frontmatter byte-for-byte unless the owner explicitly asks to change a field; malformed raw edits can desynchronize indexed data.

• Directive round-tripping is unverified. Preserve directive syntax unless the owner explicitly accepts the risk.

• Treat all boards as read-mostly. Kanban has an evidenced 400 ms debounced whole-board race. Todo, timeline, mindmap, spreadsheet, and slide use separate persistence paths whose agent-write safety is unverified.

• Treat .zudotext.settings.json, frameset state, and pins as read-only. They are whole-document last-writer-wins state, and malformed settings may silently revert to defaults.

By default the packaged skill asks for owner confirmation immediately before a whole-note replacement, delete, move, version restore, checkpoint manifest application, or cloud-agent preview application. That policy is owner-editable in the installed skill.

Optional active-note pointer

On desktop, the off-by-default active-note pointer can help a local tool orient to the note currently visible in the app. It writes only path, workspace, pane/view, selection coordinates, and timestamp — never note content — to ~/.config/zudotext/<appname>/active-note.json.

The app refreshes it every 10 seconds and on note/pane/view changes; readers treat data older than 30 seconds as stale. Disable, workspace switch, no active workspace note, and clean shutdown remove it, while a crash can leave a stale file. It is a strictly read-only sidecar, not an MCP command channel, and token creation never enables it.

Security notes

• Document keys reach bounded server memory. The local process derives raw keys with PBKDF2-SHA-256 at 600,000 iterations and opens a key session held in Durable Object memory for at most one hour. It is never persisted. Normal close and process signals start best-effort deletion; abnormal death relies on expiry.

• Asset keys and plaintext remain local. Non-extractable asset keys stay in the stdio process. /api/assets receives opaque path tokens and encrypted envelopes only; an asset-only process opens no document key session.

• Credentials remain local. Protect the PAT, MCP config, password, and password file like SSH credentials. Workspace binding prevents redirecting a bound PAT to another workspace.

• Logs are protocol-safe. Known credentials, key material, and session ids are redacted; stdout is MCP-only and logs use stderr.

• Cloud-agent history is a separate disclosure. Tool results and edit proposals can persist as plaintext excerpts in the durable conversation record. Retiring a conversation makes it unlisted and unreachable but does not immediately erase Flue's append-only storage.

Verification status

Each release is checked by building, packing, installing into a temporary prefix, verifying the installed version and exact 21-tool inventory, inspecting the tarball, and byte-checking both packaged skills. See the package reference for the durable release contract. Authenticated deployment behavior still requires operator verification with a real workspace, bound PAT, and password source; missing credentials mean unverified, never a pass.

See also

• Local Agent Authoring — canonical architecture and safety boundary.

• Personal Access Tokens — UI defaults, scopes, workspace binding, and revocation.

• Automation API — document wire contract, key sessions, limits, and typed failures.

• Assets — interactive filer and narrow agent boundary.

• Flue Agent Platform — cloud-agent ingress, edit safety, quota, and retention.

• @takazudo/zudotext-mcp — package/release and installer reference.