mcp-hub

Personal knowledge-base MCP server. Streamable HTTP, bearer tokens, one Markdown collection per tenant.

• 1. Get the token
• 2. Claude Code
• 3. Verify
• 4. Other clients
• 5. How auth works
• 6. Client tenants
• 7. Tools
• 8. Rotate / lost machine
• 9. Troubleshooting

1. Get the token

One token per tenant. Your personal one exists in exactly three places — pick any:

1. Password manager — entry mcp-hub · personal token.
2. A machine that already has it:

   claude mcp get personal-kb        # prints the Authorization header

3. The server (only from a machine with the mcp-hub SSH alias):

   ssh mcp-hub 'sed -n "s/^MCP_HUB_TOKENS=personal=\([^:]*\).*/\1/p" /srv/mcp-hub/src/deploy/.env'

Put it in a shell variable without echo or history:

read -rsp 'personal-kb token: ' PERSONAL_KB_TOKEN; echo

2. Claude Code — user scope (all projects on this machine)

claude mcp add --transport http personal-kb https://mcp.yusypenko.com/mcp \
  --scope user \
  --header "Authorization: Bearer $PERSONAL_KB_TOKEN"

claude mcp get personal-kb          # expect:  Status: ✔ Connected
unset PERSONAL_KB_TOKEN

The header is stored in ~/.claude.json (private, per user). Then inside any session:

• /mcp → personal-kb connected
• ask: “call whoami on personal-kb” → {"tenant": "personal", "scopes": ["kb:read","kb:write"], …}

3. Verify from a shell

# liveness — public, no tenant details
curl -s https://mcp.yusypenko.com/healthz; echo

# without a token: must be 401
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://mcp.yusypenko.com/mcp \
  -H 'Accept: application/json, text/event-stream' -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

# with your token: 200 and an initialize result
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://mcp.yusypenko.com/mcp \
  -H "Authorization: Bearer $PERSONAL_KB_TOKEN" \
  -H 'Accept: application/json, text/event-stream' -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

4. Other clients

Cursor / anything that takes url + headers

{
  "mcpServers": {
    "personal-kb": {
      "url": "https://mcp.yusypenko.com/mcp",
      "headers": { "Authorization": "Bearer PASTE_TOKEN_HERE" }
    }
  }
}

Codex CLI (~/.codex/config.toml)

[mcp_servers.personal-kb]
url = "https://mcp.yusypenko.com/mcp"
bearer_token_env_var = "PERSONAL_KB_TOKEN"   # export it in your shell profile

Clients that only speak stdio (Claude Desktop config, older tools)

{
  "mcpServers": {
    "personal-kb": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.yusypenko.com/mcp",
               "--header", "Authorization: Bearer ${PERSONAL_KB_TOKEN}"]
    }
  }
}

Prefer the env-var forms: the config file then holds no secret.

5. How auth works

1. TLS only. Caddy terminates HTTPS with Let's Encrypt; plain HTTP is redirected (308). The MCP container has no published port — it is reachable only from Caddy on the internal Docker network.
2. Static bearer tokens, no OAuth. The server holds a table in its environment:

   MCP_HUB_TOKENS="personal=<64 hex>:kb:read+kb:write,client-acme=<64 hex>"

   Tokens are openssl rand -hex 32. Minimum 16 chars; two tenants sharing a token is a startup error, not a warning.
3. Every /mcp request must carry Authorization: Bearer <token>. The verifier compares it against every configured tenant with a constant-time compare (hmac.compare_digest, no early exit), so timing does not reveal which prefix matched.
4. The token picks the tenant. A match yields exactly one tenant name; that name is the directory kb/<tenant>/ and every tool call is confined to it by path resolution. No tool accepts a tenant, client or collection argument — the model cannot choose or switch tenants. No match → 401; there is no default tenant (fail closed).
5. Scopes live in the table, not the token. kb:read is required for any call; kb:write additionally unlocks write_note. Read-only is the default for new tenants.
6. Revocation = rotation. There are no sessions to revoke: change the token in the table, restart the container, and the old token gets 401 on its next call.

Consequences: a token is worth exactly one tenant's notes plus (if write-scoped) the ability to add to them. A leaked token cannot reach another tenant. Rotate when a machine is lost or a contract ends.

6. Client tenants — project scope, placeholder in git

Only after that client's NDA allows notes on self-hosted infra. Register it inside the client's repo so it cannot follow you into another project:

cd ~/code/acme
claude mcp add --transport http kb https://mcp.yusypenko.com/mcp \
  --scope project \
  --header "Authorization: Bearer ${ACME_KB_TOKEN}"

# .mcp.json is committed with the ${ACME_KB_TOKEN} placeholder — never the value.
# Real value goes in .envrc (direnv) or your shell, never in git:
echo 'export ACME_KB_TOKEN=…' >> .envrc && direnv allow

When pairing or screen-sharing with a client, check /mcp: no personal or other-client server should be live in that session.

7. Tools

Write things that stay true — decisions and their reasoning, gotchas, runbooks, conventions. Not ticket or deploy status; it goes stale in place.

8. Rotate a token / lost machine

openssl rand -hex 32                                         # new token
ssh mcp-hub                                                  # on the box:
  $EDITOR /srv/mcp-hub/src/deploy/.env                       # replace the value in MCP_HUB_TOKENS, keep the name
  cd /srv/mcp-hub/src/deploy && docker compose up -d       # recreate; no rebuild
# confirm the old token is dead → must print 401
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://mcp.yusypenko.com/mcp \
  -H 'Authorization: Bearer OLD_TOKEN' -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
# then re-run the `claude mcp add` from §2 on every machine, and update the password manager

9. Troubleshooting