ckb/docs/decisions/0007-mcp-server-module.md
Michał Kopeć bbfda5a65d Sync: local changes as of 2026-10-29T13:50:12Z
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-29 14:50:12 +01:00

9.5 KiB

type tldr status decided_on decided_by affects confidence quality last_updated freshness_window_days retention
decision The opt-in `mcp` module serves the KB over MCP; remote clients read the cascade and write only to raw/inbox/ (add, withdraw own) and raw/retractions/ (request removal), never wiki/, auth is one flag (none/token/oauth), and the server runs in place from the module folder against its own clone. accepted 2026-10-29 Michał Kopeć /docs/decisions/0001-opt-in-file-based-kb-modules.md 0.8 0.8 2026-10-29 365 high

D-0007 — The opt-in mcp server module

Status: Accepted · Decided: 2026-10-29 · Deciders: Michał Kopeć

Context

The knowledge in a KB is only reachable where an agent has a checkout and the skills: Claude Code, in practice. The user wants the same knowledge in tools that accept MCP connectors, Claude's web UI above all, and wants to add new information from there, not only read it. Most of the time there is one user, but a team may follow, so authentication has to start simple and grow without a redeploy.

Claude's web app connects only to remote MCP servers: Anthropic's cloud calls the URL, so the server needs public HTTPS. The web connector also cannot send a custom header. Without OAuth, a secret must travel in the URL.

Decision

A module, not core. Serving the KB is useful to some KBs and needs a host and a Python ≥3.10 runtime, so it ships under .agents/modules/mcp/ per D-0001 / D-0001. It installs one skill (ckb-mcp) and a routing block. The server runs in place from server/, so a template upgrade replaces it with the rest of the module.

Reads follow the cascade, through the existing retrieval script. search_kb runs ckb-retrieve's retrieve_candidates.py, so remote and local answers rank alike. read_page serves wiki/, linked/, libs/, raw/inbox/, raw/archive/ and outputs/, and nothing else, except that a caller may read their own requests in raw/retractions/. A request's reason can reveal why material was confidential, so nobody else sees it. The same areas apply inside each linked/<name>/. No symlink is followed except linked/<name> itself, because a committed link such as wiki/x.md -> ../.git/config would otherwise serve whatever it points at. workload/, raw/saved-conversations/, dotfiles and *.local.yaml stay private.

Remote writes never touch wiki/. The main one is a new file in raw/inbox/; the undo paths below add a withdrawal and a retraction request. A submission carries provenance frontmatter (submitted_by, submitted_at, via: mcp, source) and is committed with the submitter as git author. ckb-ingest turns it into wiki pages, keeping the log, schema, cross-links and review where they already live.

Auth is one flag: CKB_MCP_AUTH=none|token|oauth. token takes a single secret or a per-person file with a write bit, and accepts either Authorization: Bearer or a secret path /<token>/mcp for Claude web. oauth makes the server an OAuth 2.1 resource server: it advertises an external authorization server and verifies its JWTs by JWKS, or introspects opaque tokens, with allow and writer lists. The server never issues tokens itself. Read-only is available in both modes: a read-only token or a token-file entry without write: true, an OAuth user outside the writer list, or an OAuth token missing CKB_MCP_OAUTH_WRITE_SCOPE. Read-only callers are not shown the write tools.

One server per KB, each named. Several KBs mean several instances, each with its own clone, auth and URL. Claude holds one connector per KB. CKB_MCP_NAME (default: the origin repo's name) prefixes every tool description, and CKB_MCP_DESCRIPTION goes into the server's instructions, because the tool names are identical across instances.

Every write names its KB and is confirmed by the user. With several KB connectors in one client, a misrouted write can put one client's material into another's KB. Each write tool takes a required kb argument that must equal the server's name. With CKB_MCP_CONFIRM=auto the user then confirms the write: through MCP elicitation when the client supports it on the stateless-safe 2026-07-28 protocol, and otherwise by repeating the call with a signed code. The code is bound to the KB, the caller and the exact arguments, and expires in 15 minutes. The two-step form relies on the model asking the user, so the docs also advise per-tool approval in the client, the one gate a model cannot skip.

Undo is part of the write path, and only for the person who added the document. withdraw_submission deletes the caller's own pending inbox item. request_retraction accepts only the source's submitted_by. ckb-retract re-checks this locally, falling back to the git author who added the file. Only ckb-retract in a local session may override the owner, for a maintainer who types an explicit confirmation and is logged as overriding: the KB exists to share knowledge, so a source must not be stranded when its submitter leaves or changes email. An ingested source cannot be pulled out remotely, because its content has spread into pages, claims and edges. Instead request_retraction files a request in raw/retractions/, and the core ckb-retract skill unwinds exactly what that source contributed, with the user approving the plan. Retraction is core, not module: a source filed in the wrong KB, or later found wrong, needs unwinding however it arrived.

Git: its own clone, three modes. CKB_MCP_GIT=off|commit|sync. A hosted server uses sync. Before every write it fetches and hard-resets its clone to the remote branch, applies the change, commits and pushes. A rejected push is retried once from a fresh reset; a second rejection resets again and reports that nothing was saved. Reads reset at most once per interval. The clone holds nothing but writes already pushed, so a reset loses nothing, and the clone can never diverge. That matters now that a withdrawal deletes a file someone may have edited upstream. Because sync resets, the server refuses to start on a checkout with local changes or unpushed commits: it must have its own clone, never a person's working copy.

Stateless HTTP with JSON responses. Every request stands alone, so the server survives restarts and proxies, and can run as several replicas without session affinity.

Rationale

Keeping remote writes out of wiki/ keeps them small and reviewable. Two submissions never conflict, a bad one is a file to delete rather than a page to repair, and a remote model's claims cannot enter the wiki unreviewed. Direct page edits would mean re-implementing ingest's log, schema and cross-link duties inside the server, and trusting a model that cannot see the skills to follow them.

Token mode exists because a one-person KB needs no identity provider, and Claude web needs a header-free form. OAuth is the right shape for a team, but only as a resource server: issuing tokens means storing credentials and implementing login, consent and client registration, all of which an existing IdP already does.

Consequences

  • ckb-ingest sees inbox items with via: mcp and credits submitted_by. The module's routing block tells it to treat them as unreviewed claims.
  • The server's commits arrive through ckb-sync-changes like anyone else's.
  • In token mode the URL is the secret. The server redacts it from its own access log. A reverse proxy's log is the operator's to switch off.
  • No page schema change; kb_schema_version stays 1.5.

Alternatives considered

  • A generic git or filesystem MCP server. Nothing to write, but it ignores the cascade and lets a client edit wiki/ with no log, schema or review.
  • Direct page edits, or edits on a branch for review. A branch keeps review, but a proposed edit still needs the ingest duties done by the remote model. Deferred to a possible later propose_page_edit tool. The inbox covers adding knowledge, which was the stated need.
  • Server-side confirmation only by elicitation. That gate is the strongest, but writes would fail outright for every client without elicitation on the current protocol.
  • Remote removal of ingested content. One call would undo a misfiled ingest, but it hands wiki surgery (which claims only that source supported) to a model that cannot see the skills. A request plus ckb-retract keeps a person in the loop.
  • Built-in OAuth authorization server. Self-contained, but it puts credential storage, login and client registration in the KB's tooling. Rejected in favour of verifying an external IdP's tokens.
  • One server process serving several KBs under separate paths. Fewer processes, but each KB needs its own OAuth resource metadata at the root /.well-known/ path, its own lifespan and its own access lists anyway. Containers per KB cost little and keep each KB's credentials and failures apart.
  • Syncing the wiki to Drive or Notion and using their connectors. No server to host, but writes come back outside git and search ignores the cascade.

Sources

Chat conversation, 2026-10-29: options for exposing the KB to MCP clients; the user chose a hosted, KB-aware server with OAuth as a switchable option and a likely move from one user to several. Same day: read-only access for some OAuth users and for agents on tokens, and several KBs connected to one Claude account. Same day: a misrouted write was judged unsafe with several KBs, leading to the required kb argument, user confirmation, and withdraw and retraction.