# ckb MCP server configuration. Copy to .env next to compose.example.yaml. # Docker env files do not strip inline comments: keep comments on their own lines. # Every variable is optional unless marked REQUIRED for the mode you choose. # --- Where the KB comes from ------------------------------------------------ # Clone URL, used once on first start. Recommended: an SSH URL plus a deploy key # with write access to this one repo, mounted at /run/secrets/ckb-deploy-key # (see compose.example.yaml). CKB_REPO_URL=git@git.example.com:org/kb.git # Alternative: an HTTPS URL with a token embedded # (https://ckb-mcp:@git.example.com/org/kb.git). git stores that URL, token # included, in plaintext in the clone's .git/config. The server never serves .git/, # but anyone with a shell on the host or the volume can read it. # (set by the image; for a bare-metal run, the KB root) # CKB_ROOT=/kb # (default: the clone's current branch) # CKB_MCP_GIT_BRANCH=main # CKB_MCP_GIT_REMOTE=origin # --- Identity: what clients call this KB ------------------------------------ # One client (e.g. claude.ai) can hold several KB connectors. The name prefixes # every tool description and the description tells the model what this KB covers. # Defaults: the origin repo's name, and the tldr of wiki/overview.md. # CKB_MCP_NAME=project-alpha # CKB_MCP_DESCRIPTION=Alpha migration: architecture, decisions, people # --- Network ---------------------------------------------------------------- # The public HTTPS address clients connect to, without the /mcp path. # REQUIRED for oauth (it is the token audience and the metadata URL). CKB_MCP_PUBLIC_URL=https://kb.example.com # (set by the image) # CKB_MCP_HOST=0.0.0.0 # CKB_MCP_PORT=8765 # CKB_MCP_PATH=/mcp # (proxies whose X-Forwarded-* headers are trusted) # CKB_MCP_TRUSTED_PROXIES=127.0.0.1 # (enables Host-header (DNS rebinding) checks) # CKB_MCP_ALLOWED_HOSTS=kb.example.com # --- Authentication: none | token | oauth ----------------------------------- CKB_MCP_AUTH=token # token: shared secrets ... # Claude web connector URL: https://kb.example.com//mcp # Clients that send headers: https://kb.example.com/mcp + "Authorization: Bearer " # Generate: python3 -c 'import secrets; print(secrets.token_urlsafe(32))' # Read-write (search, read, add_to_inbox): CKB_MCP_TOKEN= # Read-only (no add_to_inbox; for agents and other tools). Either or both may be set. # CKB_MCP_READ_TOKEN= # git author of inbox submissions in single-token mode CKB_MCP_AUTHOR_NAME=Your Name CKB_MCP_AUTHOR_EMAIL=you@example.com # ... or one token per person or agent, each with its own write bit # (overrides both variables above; see tokens.example.json; no "write": true = read-only) # CKB_MCP_TOKENS_FILE=/run/secrets/ckb-tokens.json # oauth: an external authorization server issues tokens; this server verifies them. # (REQUIRED, exact `iss`) # CKB_MCP_OAUTH_ISSUER=https://auth.example.com/application/o/ckb/ # (JWT access tokens) # CKB_MCP_OAUTH_JWKS_URL=https://auth.example.com/application/o/ckb/jwks/ # (opaque tokens instead (RFC 7662) ...) # CKB_MCP_OAUTH_INTROSPECTION_URL= # (... with these credentials) # CKB_MCP_OAUTH_CLIENT_ID= # CKB_MCP_OAUTH_CLIENT_SECRET= # (default: CKB_MCP_PUBLIC_URL + CKB_MCP_PATH) # CKB_MCP_OAUTH_AUDIENCE= # (space-separated scopes every token must carry) # CKB_MCP_OAUTH_SCOPES= # (introspection only: accept a response without `aud`; JWTs always need it) # CKB_MCP_OAUTH_ALLOW_MISSING_AUD=1 # Who may connect / who may write: emails, subjects, or @domain. Empty = everyone the issuer accepts. # CKB_MCP_OAUTH_ALLOWED=@example.com # CKB_MCP_OAUTH_WRITERS=you@example.com # Writing also requires this scope in the token, when set. Lets a machine client # (client credentials, no email) be read-only or read-write by the scopes it is granted. # Users outside WRITERS, or without the scope, are read-only: write tools are hidden from them. # CKB_MCP_OAUTH_WRITE_SCOPE=kb:write # --- Writes and git --------------------------------------------------------- # inbox | off (read-only server) CKB_MCP_WRITE=inbox # Every write (add, withdraw, retraction request) names its target KB, and with # auto the user confirms it: in the client's own dialog when the client supports # elicitation, else by a second call carrying a signed, expiring code. Use off # only for a KB that no client shares with another KB, or for an automated agent. CKB_MCP_CONFIRM=auto # Signs confirmation codes; random per process if unset. Set it (any long random # string) when several replicas serve one KB. # CKB_MCP_CONFIRM_SECRET= # off | commit | sync (pull before reads, push after writes) CKB_MCP_GIT=sync # (seconds between pulls) # CKB_MCP_PULL_INTERVAL=60 # (committer; the submitter is the git author) # CKB_MCP_GIT_NAME=ckb-mcp # CKB_MCP_GIT_EMAIL=ckb-mcp@localhost # CKB_MCP_MAX_INBOX_BYTES=200000