--- name: ckb-mcp description: Run, deploy, configure or connect this KB's MCP server (.agents/modules/mcp/server/), which lets Claude's web and desktop apps, Claude Code, or any MCP client search and read the KB and submit material to raw/inbox/. Use for "run the MCP server", "deploy the KB server", "connect the KB to Claude web", "add the KB as a connector", "switch MCP auth to OAuth", "add an MCP user", "give an agent read-only access", "rotate the MCP token", "serve several KBs", or "why can't Claude see my KB". --- # MCP server skill ## Purpose The server lives in `.agents/modules/mcp/server/` and runs from there. This skill sets it up and connects clients to it; it never changes what the server may read or write. That policy is in `kb.py` and [D-0007](/docs/decisions/0007-mcp-server-module.md): reads from `wiki/`, `linked/`, `libs/`, `raw/inbox/`, `raw/archive/`, `outputs/` and the caller's own requests in `raw/retractions/`. Writes are new files in `raw/inbox/`, the submitter's own withdrawals from it, and retraction requests in `raw/retractions/`. Nothing remote ever touches `wiki/`. What a client gets: `kb_overview`, `search_kb` (the `ckb-retrieve` ranking script), `read_page`, `list_pages`, `list_my_submissions`, and, unless `CKB_MCP_WRITE=off`, `add_to_inbox`, `withdraw_submission` and `request_retraction`. Also the `ckb://rules` resource (`AGENTS.md`) and the `answer_from_kb` prompt. Every setting is an environment variable; `server/env.example` lists them all with comments. Read it rather than restating it to the user from memory. The user-facing version of these steps is `docs/MCP.md` (Polish: `docs/MCP.pl.md`). Point the user there, in their language, instead of restating it at length. ## Pick the shape first Ask only what you can't infer: | Client | Transport | Where it runs | |---|---|---| | Claude Code or Claude Desktop on this machine | stdio | locally, against this checkout | | Claude web (claude.ai), mobile, or a team | HTTP | a host with public HTTPS | Claude's web app reaches **remote** servers only: Anthropic's cloud calls the URL, so `localhost` or a VPN-only address will not work for it. ## Local (stdio) Needs Python 3.10+ and `pip install -r .agents/modules/mcp/server/requirements.txt` (a venv is fine). With `CKB_MCP_GIT=off`, the default, inbox writes are plain files in this working copy, and `ckb-sync-changes` commits them as usual. ```bash claude mcp add ckb --env CKB_MCP_TRANSPORT=stdio -- \ "$PWD/.agents/modules/mcp/server/server.py" ``` Claude Desktop: the same command and `env` in `claude_desktop_config.json` under `mcpServers`. Submissions are authored as this checkout's `git config user.name`/`user.email`, the identity Rule E uses for the session, unless `CKB_MCP_AUTHOR_NAME`/`_EMAIL` override it. ## Hosted (HTTP) 1. **A clone for the server.** It needs its own clone with push access, never someone's working copy: it pulls before reads and pushes inbox commits. Recommend an SSH deploy key with write access to this repo only, mounted at `/run/secrets/ckb-deploy-key`. A token embedded in an HTTPS `CKB_REPO_URL` works, but git keeps it in plaintext in the clone's `.git/config`. Use it only when SSH is not available. 2. **Config.** Copy `server/env.example` to `.env` beside `compose.example.yaml`. Set `CKB_REPO_URL`, `CKB_MCP_PUBLIC_URL` and the auth block. Generate tokens with ` -c 'import secrets; print(secrets.token_urlsafe(32))'`, run by the user. Never put a token in the chat, a commit, the wiki or `workload/`. 3. **Run.** `docker compose -f compose.example.yaml up -d --build` from `server/`, or run `server.py` directly under systemd with the same env. 4. **TLS.** Put a reverse proxy (Caddy, Traefik, nginx) in front: public HTTPS to `127.0.0.1:8765`. Set `CKB_MCP_TRUSTED_PROXIES` to the proxy's address. With token mode in the URL path, turn the proxy's access log off for this host, or have it strip the path. The server redacts tokens from its own log, but it cannot reach the proxy's log. 5. **Check.** `curl https:///health` should return `{"status":"ok",...}` with the expected auth mode. A POST to `/mcp` without credentials should return 401. ## Connecting clients - **Claude web/desktop, token mode:** Settings → Connectors → Add custom connector, URL `https:////mcp`. The URL is the secret, so treat it like a password. - **Claude web/desktop, OAuth mode:** URL `https:///mcp`. Claude finds the authorization server through `/.well-known/oauth-protected-resource/mcp`. If the IdP has no dynamic client registration, create a client there and enter its ID and secret under the connector's Advanced settings. The redirect URI to allow is the one Anthropic's current connector docs give for custom connectors. Check those docs instead of guessing. - **Claude Code, remote:** `claude mcp add --transport http ckb https:///mcp --header "Authorization: Bearer "`. Team and Enterprise plans may need an owner to add custom connectors. When the connector cannot be added, say so; don't troubleshoot the server. ## Switching auth `CKB_MCP_AUTH` is the only switch. Restart after changing it. - **none:** allowed only on loopback, or with `CKB_MCP_ALLOW_UNAUTHENTICATED=1` behind a VPN. Never for a public host. - **token:** one person: `CKB_MCP_TOKEN` (read-write) plus `CKB_MCP_AUTHOR_NAME`/`_EMAIL`, which become the git author of submissions (default: the clone's git identity, usually empty in a container). `CKB_MCP_READ_TOKEN` adds a read-only secret beside it, or replaces it for a read-only server. Several people or agents: a `CKB_MCP_TOKENS_FILE` (shape in `tokens.example.json`). An entry is read-only unless it says `"write": true`. Adding, rotating or demoting someone means editing that file and restarting. A rotated token's old URL stops working. - **oauth:** needs an IdP that issues access tokens with this server as audience: Authentik, Keycloak, Zitadel, Auth0 and Entra ID all can. Set `CKB_MCP_OAUTH_ISSUER` (exact `iss`), `CKB_MCP_OAUTH_JWKS_URL` (or introspection for opaque tokens) and `CKB_MCP_PUBLIC_URL`. Restrict with `CKB_MCP_OAUTH_ALLOWED` / `CKB_MCP_OAUTH_WRITERS`, given as emails or `@domain`. Leave neither empty when the IdP admits outside accounts (a social login, say). An `email` claim counts only with `email_verified: true`; for an IdP that never sends that claim (Entra ID access tokens), set `CKB_MCP_OAUTH_TRUST_EMAIL=1`, else such users match only by subject. Each user's `email`/`name` claims become the git author of their submissions. `CKB_MCP_OAUTH_WRITE_SCOPE` (e.g. `kb:write`) also makes writing depend on a scope in the token. That is the way to give a machine client, which has no email, read-only or read-write access. **Read-only callers** in any mode see no write tools: `add_to_inbox` is missing from their tool list, and a direct call is refused. `CKB_MCP_WRITE=off` makes the whole server read-only. ## Several knowledge bases Run **one server per KB**. Each has its own clone, env file, auth and URL, and in Claude each becomes its own connector. `compose.example.yaml` shows two side by side. Prefer a subdomain per KB (`kb-alpha.example.com`). A shared host with path prefixes also works: `CKB_MCP_PATH=/alpha/mcp`, and the proxy must route both `/alpha/` and `/.well-known/oauth-protected-resource/alpha/` to that instance. **Keep `CKB_MCP_CONFIRM=auto` whenever a client holds more than one KB connector.** Every write must name its KB and be confirmed by the user, either through elicitation or the two-step code (the module README explains both). Also advise setting the write tools (`add_to_inbox`, `withdraw_submission`, `request_retraction`) to ask before use in each connector's settings. That gate cannot be skipped by the model. `off` is for a KB that never shares a client with another, or for an automated agent's token. Several replicas of one KB need a shared `CKB_MCP_CONFIRM_SECRET`. Only the person who added a document can withdraw it or request its retraction. Another user, or a maintainer acting through the server, is refused. A maintainer retracts someone else's source only in a local session, through `ckb-retract`'s typed override. If something lands in the wrong KB, its submitter runs `list_my_submissions` there. A pending item: `withdraw_submission`. An ingested one: `request_retraction`, then `ckb-retract` in that KB's checkout. Say plainly that git history still holds it. Give every instance a distinct `CKB_MCP_NAME`, and a `CKB_MCP_DESCRIPTION` saying what the KB covers. The name prefixes every tool description, and the description goes into the server's instructions. That is how a client holding several KB connectors knows which one to ask. By default the name is the origin repo's name, which is fine when the repos are named well. With OAuth, one IdP serves them all. Each instance is its own resource (audience = its public URL), so each needs that audience allowed at the IdP, or a shared `CKB_MCP_OAUTH_AUDIENCE`. Allow and writer lists are per instance, so who may read or write is set per project. ## Reporting Say what was configured: mode, URL shape (never the token itself), write mode, git mode. Record what was set up in `workload/` per Rule D, again without secrets. If choosing hosted access over local was a real decision for this KB, offer `ckb-decide`.