--- type: decision tldr: 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. status: accepted decided_on: 2026-10-29 decided_by: Michał Kopeć affects: /docs/decisions/0001-opt-in-file-based-kb-modules.md confidence: 0.8 quality: 0.8 last_updated: 2026-10-29 freshness_window_days: 365 retention: 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](/docs/decisions/0001-opt-in-file-based-kb-modules.md). 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//`. No symlink is followed except `linked/` 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 `//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.