# Using this knowledge base from Claude and other MCP clients *Read this in: **English** | [Polski](MCP.pl.md)* 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](decisions/0007-mcp-server-module.md). For the module's file layout, see [its README](../.agents/modules/mcp/README.md). --- ## 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: ```bash 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. 5. **Check it:** `https:///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:////mcp`. Other clients send it as `Authorization: Bearer `. 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. - 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:////mcp`. In OAuth mode, paste `https:///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:///mcp --header "Authorization: Bearer "` 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](../LICENSE).*