Knowledge Hub MCP

Tools

Tool	Purpose
`kb_search(query, top_k?, scope_prefix?)`	Semantic search; returns chunks with `kh-id` citations.
`kb_fetch(kh_id)`	Full document content + frontmatter for a stable `kh-id`.
`kb_list_scope(prefix?)`	List nodes under a scope prefix; omit for the full tree.
`kb_node(kh_id)`	Single node plus 1-hop neighbours (`related`, `derived_from`).

The server is read-only by design. Writes go through the Amos admin UI (humans) or the worker’s diary writer (agents).

Transport

Selected at runtime by KB_MCP_TRANSPORT. The same binary handles all three:

Value	When to use
`stdio` (default)	Local clients — Claude Desktop, `claude mcp add`. The client execs the binary; stdio is the wire.
`streamable-http`	The in-cluster deployment and any partner-tier endpoint. Spec-current MCP transport.
`sse`	Older HTTP clients that don’t yet speak streamable-http.

HTTP modes bind to KB_MCP_BIND_HOST:KB_MCP_BIND_PORT (default 0.0.0.0:8080). When KB_MCP_AUTH_TOKEN is set, every HTTP request must carry Authorization: Bearer <token> — enforced by Starlette middleware with constant-time comparison. Leaving the token unset is correct for cluster-internal-only deployments where NetworkPolicy or ingress owns the trust boundary.

Configuration

Variable	Required	Default	Notes
`KB_MCP_TRANSPORT`	no	`stdio`	`stdio` \| `streamable-http` \| `sse`. Aliases `http` and `streamable_http` accepted.
`KB_MCP_BIND_HOST`	HTTP only	`0.0.0.0`	uvicorn host.
`KB_MCP_BIND_PORT`	HTTP only	`8080`	uvicorn port.
`KB_MCP_AUTH_TOKEN`	HTTP recommended	—	Bearer token required on `/mcp` requests when set.
`MOTHER_AI_URL`	yes	—	Amos Mother AI endpoint.
`MOTHER_AI_API_KEY`	depends	—	Required when Mother AI has it set.
`KB_MCP_ACTOR`	no	`mcp:local` (stdio) / `mcp:cluster` (HTTP)	Per-client identifier in audit rows.
`KB_MCP_TIMEOUT_S`	no	`20`	Upstream HTTP timeout.
`KB_MCP_LOG_LEVEL`	no	`INFO`	stderr only on stdio; stdout is reserved for the wire.

Cluster deployment

The amos-mcp Terraform module (terraform/modules/amos-mcp/) ships a Deployment + ClusterIP Service. Workers and other in-cluster tooling reach it at:

http://amos-mcp.amos.svc.cluster.local/mcp

A public ingress is templated but gated by mcp_public_enabled (default off). When enabled it attaches to the existing ingress-nginx with per-IP rate limiting; the auth token is enforced by the server middleware, not the ingress, so token rotation only touches the K8s Secret.

Local install (stdio)

cd mcp/amos-kb
pip install -e .

Wire into Claude Desktop via claude_desktop_config.json, or via Claude Code:

claude mcp add amos-kb --command amos-kb-mcp

Invariants

stdout is reserved for the MCP wire protocol on stdio transport. All logs go to stderr.
The server is stateless beyond its HTTP client. Audit rows, search index, and tier rules all live in Mother AI / Qdrant / Postgres.
Errors from Mother AI (auth, rate limit, tier-denied) flow through unchanged so the client can surface them to the user.
Auth checks use constant-time comparison. No token-length oracle to unauthenticated callers.

Architecture

Components

Knowledge Hub MCP

Tools

Transport

Configuration

Cluster deployment

Local install (stdio)

Invariants

​Tools

​Transport

​Configuration

​Cluster deployment

​Local install (stdio)

​Invariants

Tools

Transport

Configuration

Cluster deployment

Local install (stdio)

Invariants