9.4 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)
- 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.
- Configure it. Copy
server/env.exampleto.envand set at leastCKB_REPO_URL,CKB_MCP_PUBLIC_URLand the auth settings (step 3). That file explains every setting. - Start it with
docker compose -f compose.example.yaml up -d --buildfrom theserver/folder, or runserver.pyunder systemd with the same environment. - 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.
- Check it:
https://<host>/healthshould 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": truefor that person in the tokens file. - With OAuth: anyone not on
CKB_MCP_OAUTH_WRITERSis read-only. An agent with no email can be made read-only with theCKB_MCP_OAUTH_WRITE_SCOPEscope. - 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, pastehttps://<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
- Every write names its KB. The server rejects a write whose
kbdoesn't match its own name, so material sent to the wrong connector is refused, not filed. - 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.
- 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
- In that KB's connector, ask Claude: "What have I sent to this KB?"
- Still pending (not ingested): "Withdraw it." The file is deleted.
- 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. - The KB's maintainer runs a local session.
ckb-ingestandckb-lintflag the request, andckb-retractshows 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. - 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.