Kanban agent connections

Restricted Kanban access lets an external agent use approved boards as shared state. It does not launch agents, schedule tasks or promise background progress. Use the portable workflow for reading, conditional claiming, progress and actual result/PR links. Board reads return ordered stable column IDs in columns and effective display labels in columnLabels. Resolve labels to those IDs before create/move/restore; ambiguous labels need clarification. This page is a contributor setup and acceptance runbook, not a claim of production availability.

Readiness and permission boundary

This capability ships in npm @takazudo/zudotext-mcp@0.2.0 and later; 0.1.1 does not contain it. Publishing the package is not live-client, OAuth or native acceptance, which all remain unverified (see the acceptance record below). Pair it with the matching captured-base app and configured Worker. The setup examples are not authorization to publish, deploy, provision credentials or create a persistent grant. Obtain action-time approval before creating those grants/credentials or expanding access, and use authorized disposable boards for acceptance.

The operator must have configured the HTTPS issuer, real OAuth KV binding, existing first-party login and database migrations through the approved delivery process. Missing configuration is a blocker, not an invitation to run a manual deployment. The canonical MCP URL is https://YOUR_APPROVED_HOST/api/v1/kanban/mcp; only the eight Kanban tools are exposed. The same schemas are accepted by POST /api/v1/kanban/tools/{toolName}. See Restricted Kanban external access for the authoritative contract.

In Settings → External Connections, review the client, one workspace, server-verified existing boards and read/write permissions before connecting. Selection covers current and future direct-child Markdown cards, including archived/orphan cards; it excludes nested directories, assets and generic files. A moved, replaced or recreated manifest requires a new board approval. A raw ID, title, path or tool listing is never permission to access another board.

For a local connection, Intended external service describes the intended recipient only. The restricted PAT is portable: anyone holding it can use the connection's current permissions. Selecting a service does not authenticate or bind that token to its application. OAuth uses the provider-established client; a displayed client name alone is not identity proof.

Connecting creates a locked grant. Unlock is a separate first-party action, lasting at most 24 hours and possibly less after eviction or deployment. Selection validation temporarily sends workspace keys to the Worker; unlock enrolls the memory-only lease. These are workspace-wide keys, so board restrictions are server authorization, not per-board cryptographic isolation. A dedicated agent workspace reduces that key-custody boundary. Selected card content reaches the external service. Enter passwords only in first-party screens, never agent chat or MCP configuration. Built-in Workspace AI consent and agent:invoke remain separate; external card editing neither invokes nor authorizes that AI.

Lock ends the usable lease; Disconnect revokes the connection. Make read-only and Remove board reduce authority using the observed grant revision. Refresh the list after another device changes it; never silently retry an old management revision. Last successful mutation is receipt activity, not proof of reads or background work. WORKSPACE_LOCKED / KEY_SESSION_EXPIRED requires first-party re-unlock. OAuth refresh cannot unlock or extend the lease. Revoked access requires new approval, not a refreshed token. Client removal alone is not a substitute for first-party revocation. Cancelling before submission creates no grant; a submitted request may finish after local cancellation or response loss. Refresh and reconcile its actual result, then Lock or Disconnect an unwanted connection. Do not assume closing the screen rolled it back.

Local restricted package

From the reviewed checkout, install pinned dependencies and build the package using the repository's normal guarded build procedure. The manager's package verification command also creates and tests a temporary installed tarball:

pnpm --dir packages/zudotext-mcp release:verify -- --expected-tag zudotext-mcp-v0.2.0

Use the built package’s absolute dist/cli.js path from that checkout, or install an operator-supplied verified local tarball into an isolated prefix. Check its commit/provenance and inventory; --version alone cannot distinguish it from the published package of the same version. Do not use npx ...@latest as a feature install.

A local connection supplies an independently restricted PAT through Create restricted token after approval. Store it in the host's secret facility and provide ZUDOTEXT_PAT only to this process. Set ZUDOTEXT_MCP_PROFILE=kanban and ZUDOTEXT_SERVER_URL to the HTTPS origin. No workspace ID or password is needed. Never expose the normal authoring profile through a tunnel. Existing generic local note/asset authoring remains a separate setup under MCP integration (Claude Code and Codex).

Install the matching skill from this checkout's installer, or the verified package's zudotext-mcp-install-skill, for the chosen harness. An installed older skill must be deliberately updated; back up owner customizations first.

node packages/zudotext-mcp/skills/install-skill.mjs --harness codex --project "$PWD"
node packages/zudotext-mcp/skills/install-skill.mjs --harness claude-code --project "$PWD"

ChatGPT custom remote MCP/plugin

In ChatGPT Plugins, use the plus button → Add custom MCP server. Enter the canonical HTTPS MCP URL under Connection and configure OAuth. Review the risk notice, then Create as a plugin and inspect the discovered tools. Install it and select it with @ in a new conversation. Account/workspace policy must permit custom servers. This is the current documented flow, not evidence that this account has it enabled. OpenAI connection guide (checked 2026-10-10).

Use CIMD or an operator-approved predefined client. This Worker supports S256, the canonical resource and kanban:read/kanban:write, and has no public DCR endpoint. Do not invent a callback or enable DCR to hide an incompatible client. Complete first-party login, board review and consent, then explicitly unlock in zudo-text. OpenAI OAuth contract (checked 2026-10-10). Verify exactly eight tools and a successful approved-board read before attempting the acceptance writes below. Host write confirmations remain in force; read-only annotations apply only to reads.

Codex CLI and IDE

Codex supports stdio and Streamable HTTP, including OAuth. Its CLI and IDE share host MCP configuration; the IDE also offers MCP servers in its gear menu. Use CIMD where supported, or an approved predefined client with the exact callback shown by codex mcp add. Check the installed CLI's help before applying flags. Official MCP setup (checked 2026-10-10).

codex --version
codex mcp add --help
codex mcp add zudotext-kanban --url https://YOUR_APPROVED_HOST/api/v1/kanban/mcp
codex mcp login zudotext-kanban

For local stdio, this non-secret TOML uses the reviewed build and forwards the restricted PAT from the approved parent environment:

[mcp_servers.zudotext_kanban]
command = "node"
args = ["/ABSOLUTE/REVIEWED_CHECKOUT/packages/zudotext-mcp/dist/cli.js"]
env_vars = ["ZUDOTEXT_PAT"]

[mcp_servers.zudotext_kanban.env]
ZUDOTEXT_MCP_PROFILE = "kanban"
ZUDOTEXT_SERVER_URL = "https://YOUR_APPROVED_HOST"

Use /mcp to check the running client and invoke $zudotext-authoring from the matching installed skill. A configuration listing or successful login alone is not a tool-call acceptance pass.

Claude Code

Claude Code supports local stdio and remote HTTP, discovers CIMD, and offers /mcp for authentication/status. A predefined client can use --client-id and --callback-port; register the exact callback for the installed version. Do not assume a DCR-only client works with this Worker. Official Claude Code MCP guide (checked 2026-10-10).

claude --version
claude mcp add --help
claude mcp add --transport http zudotext-kanban https://YOUR_APPROVED_HOST/api/v1/kanban/mcp

For local stdio, start Claude from the approved environment containing the restricted ZUDOTEXT_PAT, then register the reviewed package without putting the secret in command arguments:

claude mcp add --transport stdio zudotext-kanban \
  --env ZUDOTEXT_MCP_PROFILE=kanban \
  --env ZUDOTEXT_SERVER_URL=https://YOUR_APPROVED_HOST \
  -- node /ABSOLUTE/REVIEWED_CHECKOUT/packages/zudotext-mcp/dist/cli.js

Open /mcp in Claude Code, authenticate the remote option if needed, and invoke /zudotext-authoring. Verify the actual inherited environment and eight-tool inventory. If the host strips credentials, configure its approved secret delivery; never paste them into a prompt or committed .mcp.json.

Codex Cloud and scoped HTTPS fallback

Check the active hosted environment's connected tools and permissions first. Local Codex configuration does not prove a cloud MCP route exists. If an approved remote plugin is available, verify discovery/authentication and a real read from that host; otherwise record that route as unavailable. The official MCP guide explicitly distinguishes local and cloud transports.

An approved fallback is a scoped REST request from the cloud shell. Configure a network secret named ZUDOTEXT_KANBAN_NETWORK_PAT with only the approved Worker domain and a separately authorized restricted PAT. The proxy substitutes its placeholder on HTTPS port 443; it does not deliver raw credentials to the process. Review the saved network policy. Do not request broader egress or put the secret in source, chat or logs. Cloud environment configuration (checked 2026-10-10).

After those prerequisites, this read-only diagnostic uses the placeholder. Replace only the non-secret approved host. Do not add verbose tracing or redirect following.

curl --fail-with-body --silent --show-error \
  --proto '=https' \
  --header "Authorization: Bearer ${ZUDOTEXT_KANBAN_NETWORK_PAT:?configure approved network secret first}" \
  --header 'Content-Type: application/json' \
  --data '{}' \
  https://YOUR_APPROVED_HOST/api/v1/kanban/tools/list_kanban_boards

Subsequent calls POST the same strict tool JSON, including exact read revisions and retained operation keys for mutations. A shell HTTPS result is REST/CLI fallback evidence, not native hosted-MCP acceptance. zudotext-mcp itself is a stdio server, not a create/move task CLI. If neither host route nor approved network-secret setup exists, stop that client check and retain its pending gate.

Optional personal Secure MCP Tunnel

Treat this as a separate, optional OpenAI route. Platform tunnel management/use permissions and ChatGPT workspace custom-server permissions are independent. Associate the tunnel with the intended organization/workspace, including personal account context; membership in one does not grant the other. Run tunnel-client on a trusted host with outbound HTTPS and access to only the restricted eight-tool server. The host/client must stay available for discovery and calls; sleeping a laptop stops access. Official Secure MCP Tunnel guide (checked 2026-10-10).

Follow that guide's current init, doctor and run commands after separate approval for its runtime credential and associations. No tunnel is provisioned by this feature. Never tunnel generic local-file/asset tools or infer Claude Code or other-vendor compatibility from OpenAI tunnel support. A tunnel does not extend zudo-text's key lease or replace board grants.

Remote TODO documents on the same issuer

TODO document connections use the same issuer, token endpoint, consent screens and grant table, under a separate protected resource. The canonical TODO MCP URL is https://YOUR_APPROVED_HOST/api/v1/kanban/todo/mcp; it exposes only the seven TODO tools, and POST /api/v1/kanban/todo/tools/{toolName} accepts the same audience. Its protected-resource metadata is at /.well-known/oauth-protected-resource/api/v1/kanban/todo/mcp, and a 401 or 403 from either route names that document in WWW-Authenticate.

claude mcp add --transport http zudotext-todo https://YOUR_APPROVED_HOST/api/v1/kanban/todo/mcp
codex mcp add zudotext-todo --url https://YOUR_APPROVED_HOST/api/v1/kanban/todo/mcp

Request todo:read, plus todo:write only when the agent must edit items. The resource parameter, not the consent page, decides which family is being authorized: Kanban scopes on the TODO resource, TODO scopes on the Kanban resource, a mix of both, and a TODO request without resource are refused before any consent page is shown. The consent screen lists Markdown documents, and the server accepts only existing documents with type: todo; edit permission is a separate checkbox. The new connection is locked. Unlock it in Settings → External Connections, where it appears in the TODO document connections list. A Kanban token never reaches TODO tools and a TODO token never reaches Kanban, generic document, search, history, checkpoint, asset or agent routes. Moving, deleting or recreating an approved document ends access to it. See Format-aware TODO item tools for the authority contract.

Acceptance record and safe resume

Tracking remains S5 #7486, with one epic progress record. As of 2026-10-10, the named-client cycle is PENDING for every row:

The actual Codex diagnostic ran on Linux 6.18.44 x86_64 at approximately 2026-10-10 19:41:20 UTC with the existing login, an empty working directory and this bounded command (the directory must exist):

timeout 45 /opt/codex/bin/codex exec --ephemeral --ignore-user-config \
  --skip-git-repo-check -C /tmp/kanban-7481/s5-client-empty -s read-only \
  -c project_doc_max_bytes=0 -c features.shell_tool=false --json \
  'This is a bounded client availability check. Do not use tools, read files, inspect credentials, or perform external actions. Reply exactly CLIENT_READY.'

It started a thread/turn, retried websocket access five times with HTTP CONNECT 403, then its own HTTPS fallback also failed. The timeout exited 124 without CLIENT_READY. No local fixture was launched and no Kanban tool was called. This is actual client availability evidence, not an integration pass. Restore approved model connectivity before retrying; do not work around the proxy policy.

Existing local evidence is separate: S4 ran the real bundled Worker and pinned OAuth provider in workerd (19 protocol/transport/inventory checks), MCP package 327 tests and installed tarball smoke (the previous combined 29-tool authoring registry / 8 restricted tools). The current profile contract separates 21 authoring tools from 8 restricted Kanban tools and requires fresh package verification; the earlier counts do not prove this contract. Those include actual SDK clients and mock/in-process tests, not the named applications above. S2 separately covers UI debounce/offline conflicts with mounted renderer, bridge, outbox and real Worker sequences. Final integrated review and exact-head verification remain required; these earlier passes do not certify the final app.

The foundation b4push at 5d62dc330dc25bbe8d5e5674b8394c7c50975743 had two renderer failures / 11,155 passes; unchanged focused retry passed 41/41. Its aggregate remains FAIL. Pinned Chromium 145 download returned 403 on normal and escalated attempts, so browser global setup failed and no browser test ran. System Chromium 151 is diagnostic-only. The designated disposable-account helper could not resolve its Dropbox root; no credentials or grants were provisioned. Do not substitute personal boards or invent a live pass.

Resume prerequisites and checks

Restore the authorized disposable-account workflow on a supported executor, install the intended client without changing production, and verify the approved matching Worker/app build. Record commit, client version, OS/host, account/workspace capability and transport. Obtain permission at the persistent connection/token creation step. Run the applicable setup above, with the disposable board chosen in first-party consent; record cancellation before approval as well.

Run this sequence in each actual client, keeping redacted arguments, timestamps, returned IDs/revisions/receipts, visible confirmation behavior and expected versus actual outcomes. Secrets, passwords, raw keys and internal lease IDs are excluded.

1. Connect → review consent → confirm initially locked → explicitly unlock → list/read the approved board/card. Record exactly eight advertised tools.

2. Create → read → edit → conditional move → archive → restore, reading afresh before each mutation. Retry one lost response identically and verify one result.

3. Have two authorized agents claim one disposable card from the same observed column/revision. Verify one success and one conflict; the loser stops/re-reads.

4. Verify wrong board, wrong client/connection and read-only write denial. Confirm UI body debounce versus agent move and offline/relaunch versus archive/delete retain the S2 behavior on the matching app; do not infer it from tool success.

5. Verify explicit lock, expiry and key-holder eviction. An OAuth refresh must not recreate the lease. Re-unlock explicitly, then revoke while the token remains unexpired and verify reads/writes/replays fail. Clean up disposable residue through the approved workflow; record anything left behind.

For local non-account rechecks, use these exact focused commands from the repo:

pnpm --filter @takazudo/zudotext-mcp exec vitest run skills/skill-contract.test.mjs skills/install-skill.test.mjs docs-inventory.test.mjs
pnpm --filter @takazudo/sync-server exec vitest run test/kanban/oauth-protocol.test.ts test/kanban/transports.test.ts test/agent-route-inventory.test.ts

The manager runs final pnpm b4push on the integrated commit (its script already uses the heavy guard). Resume its configured browser lane only once pinned Chromium is available. Run pnpm exam on real macOS for its native/platform gates; Linux or a substitute browser cannot certify them. Record each actual-client and native result independently in the existing issue before closing acceptance.