ckb/docs/MCP.md
Michał Kopeć 84018323a2 Template 2.0.4: secret scan coverage, mcp and capture hardening
Fixes F17-F19 from the 2.0.0 script review:
- lint check 15 scans hidden folders, key files, dotfiles and
  extensionless text; finds unquoted secret-looking assignments; reports
  files over 50 MB instead of skipping them silently
- mcp: search filtered by the read policy, query after `--`,
  case/trailing-dot-insensitive .local.yaml refusal, verified OAuth
  email only, DNS-rebinding protection on by default, single-use codes
- capture: link-local/metadata always refused, private networks need
  --allow-private (also on redirects), total download limit, charset
  fallback and <meta charset>, <form> kept, svg title ignored, safe
  collision-free binary names with dedup

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 15:46:38 +01:00

9.9 KiB

Using this knowledge base from Claude and other MCP clients

Read this in: English | Polski

The optional mcp module puts this knowledge base behind an MCP server. You can then search it, read it and add to it from Claude's web, desktop and mobile apps (as a custom connector), from Claude Code, or from any other agent that speaks MCP. You don't need a checkout of the repo on the device you're using.

This guide is for the person setting it up and using it. For the design reasons behind it, see D-0007. For the module's file layout, see its README.


What a connected client can do

You say (in Claude) What happens
"What do we know about the Atlas retry policy?" Claude searches the KB, reads the pages it relies on, and answers with page paths cited
"Add this to the KB: ..." The material goes to raw/inbox/ as a new file, with your name, the date and the source. It is not in the wiki yet: the next "Ingest" in a local session turns it into pages
"What have I sent to this KB?" Lists your submissions: still pending, or already ingested along with the pages built from them
"Take back what I just sent, it was the wrong KB" Withdraws a pending submission (the file is deleted)
"Remove what came from that note, it belonged in another KB" For a submission that was already ingested: files a request in raw/retractions/. The next local session carries it out with ckb-retract after you approve the plan

A remote client never edits wiki/ directly. Ingest and retraction stay in your local sessions, where the log, the page schema and the review steps apply.

Only the person who added a document can withdraw it or ask for its removal. A maintainer can still retract any source in a local session, with typed confirmation, so nothing is stranded when its submitter has left.


1. Install the module

In a local session, say "install the mcp module". That adds the ckb-mcp skill and records the module in ckb.yaml. The server itself lives in .agents/modules/mcp/server/ and does nothing until someone starts it.

From then on, "help me deploy the MCP server" or "connect the KB to Claude web" walks you through the rest. The steps below are the same, written out.


2. Choose where it runs

You want it in Run it Notes
Claude Code or Claude Desktop on this computer locally, over stdio Nothing to host. Submissions are plain files in your working copy
Claude on the web or mobile, or for a team on a server with public HTTPS Claude's web app calls the URL from Anthropic's cloud, so localhost or a VPN-only address won't work

Locally (stdio)

You need Python 3.10 or newer, then:

pip install -r .agents/modules/mcp/server/requirements.txt
claude mcp add ckb --env CKB_MCP_TRANSPORT=stdio -- \
  python3 "$PWD/.agents/modules/mcp/server/server.py"

Submissions are authored as your git config user.name/user.email. ckb-sync-changes commits them like any other change.

Hosted (HTTPS)

  1. Give the server its own clone with push access. Never point it at someone's working copy: before every write it resets its clone to the remote, and it refuses to start on a clone with local changes. Use an SSH deploy key with write access to this one repo.
  2. Configure it. Copy server/env.example to .env and set at least CKB_REPO_URL, CKB_MCP_PUBLIC_URL and the auth settings (step 3). That file explains every setting.
  3. Start it with docker compose -f compose.example.yaml up -d --build from the server/ folder, or run server.py under systemd with the same environment.
  4. Put a reverse proxy in front (Caddy, Traefik, nginx) for HTTPS. In token mode, switch off the proxy's access log for this host, because the token is part of the URL. The server answers only to the host in CKB_MCP_PUBLIC_URL and to loopback (protection against DNS rebinding). If the proxy passes a different Host header, list the names in CKB_MCP_ALLOWED_HOSTS; * turns the check off.
  5. Check it: https://<host>/health should answer {"status":"ok",...}.

3. Choose how people sign in

One setting, CKB_MCP_AUTH, decides. You can change it later and restart, and nothing else needs to change.

Mode Good for How it works
token you alone, a few people, agents A long secret. Claude's web app uses it in the URL: https://<host>/<token>/mcp. Other clients send it as Authorization: Bearer <token>. One read-write token (CKB_MCP_TOKEN), one read-only token (CKB_MCP_READ_TOKEN), or a file with one token per person or agent
oauth a team People sign in through your identity provider (Authentik, Keycloak, Zitadel, Auth0, Entra ID...). You list who may connect and who may write, by email or @domain
none local stdio only The server refuses to run this way on a public address

Read-only access.

  • With tokens: use CKB_MCP_READ_TOKEN, or leave out "write": true for that person in the tokens file.
  • With OAuth: anyone not on CKB_MCP_OAUTH_WRITERS is read-only. An agent with no email can be made read-only with the CKB_MCP_OAUTH_WRITE_SCOPE scope.
  • With OAuth, an email counts only when the identity provider marks it verified (email_verified). If yours never sends that (Entra ID access tokens), set CKB_MCP_OAUTH_TRUST_EMAIL=1.
  • Either way, read-only users don't even see the write tools.

Treat a token URL like a password. To revoke one, change the token and restart; the old URL stops working.


4. Connect Claude

  • Claude web/desktop/mobile: Settings → Connectors → Add custom connector. In token mode, paste https://<host>/<token>/mcp. In OAuth mode, paste https://<host>/mcp; Claude finds your identity provider on its own. If the provider doesn't support automatic client registration, create a client there and enter its ID and secret under Advanced settings. Anthropic's connector documentation lists the redirect URI to allow.
  • Claude Code (remote): claude mcp add --transport http ckb https://<host>/mcp --header "Authorization: Bearer <token>"

On Team and Enterprise plans, an owner may have to allow custom connectors first.

Recommended: in the connector's settings, set the write tools (add_to_inbox, withdraw_submission, request_retraction) to ask before use. Then nothing is written without you approving it in Claude's own dialog.


5. Several knowledge bases in one Claude

Run one server per KB, each with its own clone, URL and access settings, and add each as its own connector. compose.example.yaml shows two side by side. A subdomain per KB (kb-alpha.example.com) is the simplest setup.

Give each a clear CKB_MCP_NAME and a one-line CKB_MCP_DESCRIPTION. Every tool description starts with the name, so Claude can tell which KB it is asking.

How it keeps material out of the wrong KB

  1. Every write names its KB. The server rejects a write whose kb doesn't match its own name, so material sent to the wrong connector is refused, not filed.
  2. You confirm every write. If the client supports it, the server asks you directly: "Add “Kickoff notes” to the 'alpha' knowledge base?". Otherwise Claude gets a question and a confirmation code, and has to ask you before it may repeat the call with the code. The code works only for that KB, that person and that exact content, and expires after 15 minutes.
  3. Mistakes can be undone (see the next section).

The confirmation code relies on Claude actually asking you. The ask before use setting from step 4 is the one gate the model cannot skip, so use it whenever more than one KB is connected. CKB_MCP_CONFIRM=off is only for a KB that never shares a client with another one, or for an automated agent.


6. When something went to the wrong KB

  1. In that KB's connector, ask Claude: "What have I sent to this KB?"
  2. Still pending (not ingested): "Withdraw it." The file is deleted.
  3. Already ingested: "Request its removal, it belongs in project-beta." That files a request in raw/retractions/. Only the account that made the request can see it.
  4. The KB's maintainer runs a local session. ckb-ingest and ckb-lint flag the request, and ckb-retract shows exactly what the source built: pages to delete, claims to remove, edges. Nothing is removed until they approve. Claims another source also supports are kept.
  5. Add the material to the right KB through its own connector.

What retraction cannot do: it fixes the KB only as it is now. The content is still in git history, on the remote, in every clone and in the server's clone. If it was confidential (another client's material, personal data), removing it from history is a separate, deliberate history rewrite with a force-push. ckb-retract explains this but never does it.


Troubleshooting

Symptom Likely cause
Claude says it can't reach the connector The URL isn't public HTTPS, or the proxy doesn't forward /mcp (and, for OAuth, /.well-known/oauth-protected-resource/...)
Every request gets 401 Wrong or rotated token. In OAuth mode, check the server log: a wrong JWKS URL or an unreachable identity provider is logged as token verification failed
Claude can read but has no write tools Your token or account is read-only, or CKB_MCP_WRITE=off
A write is refused with This connector is the 'X' KB... Claude chose the wrong connector. Nothing was written
The server won't start: CKB_MCP_GIT=sync resets ... Its clone has local changes or unpushed commits. Give it a clean, dedicated clone
Writes report nothing was saved - please try again The remote kept changing during two attempts. Retry; nothing was left half-done

Licensed under the Apache License, Version 2.0 - see LICENSE.