9.1 KiB
| name | description |
|---|---|
| ckb-mcp | 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: 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.
claude mcp add ckb --env CKB_MCP_TRANSPORT=stdio -- \
<python> "$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)
- 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 HTTPSCKB_REPO_URLworks, but git keeps it in plaintext in the clone's.git/config. Use it only when SSH is not available. - Config. Copy
server/env.exampleto.envbesidecompose.example.yaml. SetCKB_REPO_URL,CKB_MCP_PUBLIC_URLand the auth block. Generate tokens with<python> -c 'import secrets; print(secrets.token_urlsafe(32))', run by the user. Never put a token in the chat, a commit, the wiki orworkload/. - Run.
docker compose -f compose.example.yaml up -d --buildfromserver/, or runserver.pydirectly under systemd with the same env. - TLS. Put a reverse proxy (Caddy, Traefik, nginx) in front: public HTTPS
to
127.0.0.1:8765. SetCKB_MCP_TRUSTED_PROXIESto 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. - Check.
curl https://<host>/healthshould return{"status":"ok",...}with the expected auth mode. A POST to/mcpwithout credentials should return 401.
Connecting clients
- Claude web/desktop, token mode: Settings → Connectors → Add custom
connector, URL
https://<host>/<token>/mcp. The URL is the secret, so treat it like a password. - Claude web/desktop, OAuth mode: URL
https://<host>/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://<host>/mcp --header "Authorization: Bearer <token>".
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=1behind a VPN. Never for a public host. - token: one person:
CKB_MCP_TOKEN(read-write) plusCKB_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_TOKENadds a read-only secret beside it, or replaces it for a read-only server. Several people or agents: aCKB_MCP_TOKENS_FILE(shape intokens.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(exactiss),CKB_MCP_OAUTH_JWKS_URL(or introspection for opaque tokens) andCKB_MCP_PUBLIC_URL. Restrict withCKB_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). Each user'semail/nameclaims 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.