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-ingestsees inbox items withvia: mcpand creditssubmitted_by. The module's routing block tells it to treat them as unreviewed claims.- The server's commits arrive through
ckb-sync-changeslike 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_versionstays1.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_edittool. 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-retractkeeps 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.