The Production MCP Playbook — Packaging, Registration, Deployment, Audit Lab

The Close-Out Ritual

Every software project has a close-out ritual — the final steps before you call something production-ready. For most REST APIs, it is: staging environment pass, load test, deploy to prod, monitor dashboards for 24 hours.

For MCP servers, the ritual is different because the consumer is an AI model and the failure modes are different. You need to verify that tool schemas are understood correctly by the model, that auth works at the middleware layer, that the output shape is stable, and that health checks prove the pipeline — not just the process.

The Production MCP Playbook is this ritual. It is the sequence Knox followed to ship Semantic Memory Layer, mcp-bridge, and the agent dispatch bridge. It is the same sequence you should follow for any MCP server you intend to run in production.

The Four-Phase Playbook

The playbook is sequential. Each phase has prerequisites from the previous phase. You cannot register before you package. You cannot audit before you deploy. The urge to skip phases — especially Phase 4 (audit lab) — is the urge that causes production incidents.

Phase 1: Package. Compile TypeScript to JavaScript. Build a Docker image with a pinned base image (node:20-alpine, not node:latest) and a non-root user. The non-root user is not optional — containers should always follow the principle of least privilege: running as root gives a compromised process unnecessary access to the host system.

Phase 2: Register. The ~/.claude.json entry is the contract between your server and every Claude Code session that will use it. Note that ~/.claude/settings.json is a different file — it governs hooks, permissions, and env configuration, not MCP server registration. The URL must point to the /mcp endpoint, not the /health endpoint. The Authorization header must use the correct token for the scope level you are granting to Claude Code sessions. After registering, close Claude Code completely and reopen — MCP servers load at session start, not on registration.

Phase 3: Deploy on the Production Server. SSH to the production server (ssh 192.0.2.10). The PATH export is mandatory: non-interactive SSH sessions do not inherit Homebrew on PATH, so docker is not found by default (export PATH=/opt/homebrew/bin:/usr/local/bin:$PATH). After deploying, verify with lsof -i -P | grep <your-port> that exactly one PID holds the port. If two PIDs: split-brain. Kill the launchd plist.

Phase 4: Audit Lab. Run all 16 checks. No skipping.

The 16-Check Audit Lab

The audit lab is the production gate. It covers the four dimensions that matter: security, schema contracts, read/write safety, and health proof. Every check has an expected outcome. A server that passes all 16 is ready for production registration.

The checks you are most likely to fail on first run:

Check 3 (log grep for bearer/auth): Most developers log req.headers in error handlers during development. The auth header is there. Find it, remove it, redact it.

Check 9 (memory_remember → memory_recall verification): This fails if the write-path has any inconsistency — split-brain, embedding failure, volume mount issue. It is the most important single check in the lab.

Check 13-16 (health proof): These require actually writing memories and verifying the chunk count grows. Most developers run these last, when they are tired. Do not skip them.

The ~/.claude.json Pattern

The mcpServers block lives in ~/.claude.json — not ~/.claude/settings.json, which is a separate file that governs hooks, permissions, and environment configuration. The complete registration for three production MCP servers:

{
  "mcpServers": {
    "memory-service": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer ${MEMORY_READ_TOKEN}"
      }
    },
    "mcp-bridge": {
      "type": "http",
      "url": "http://localhost:8081/mcp"
    },
    "agent-bridge": {
      "command": "ssh",
      "args": [
        "192.0.2.10",
        "node /opt/services/agent-bridge/dist/index.js"
      ]
    }
  }
}

Three patterns: HTTP with auth header, HTTP without auth (localhost only, internal service on a different port), and stdio via SSH for the agent dispatch bridge (which runs on the production server and uses its own local auth). All three are valid production patterns for their respective use cases.

What Running Semantic Memory Layer in Production Actually Looks Like

After passing the audit lab:

• Claude Code sessions on your laptop call memory_query at session start with the project name. Relevant architectural context surfaces before a single file is read.
• The agent gateway on the production server calls memory_remember after every correction from Knox, every resolved incident, and every new lesson learned. The memory store grows.
• The ingest-corpus cron adds academy lessons to the index on every merge to main. The lessons namespace grows from ~900 chunks to ~1,100 chunks over the batch-1 build.
• The L3 health check runs every 6 hours via a cron on the production server. If chunks_indexed stops growing or last_indexed_at exceeds 24 hours, an alert fires to Discord.
• lsof -i -P | grep <your-port> runs in the deploy-preflight skill before any production server deployment that touches the MCP server. Two PIDs stops the deploy.

This is the production operating rhythm. It is not glamorous. It is disciplined. The discipline is what makes the system compound: every correction becomes a memory, every memory surfaces in the next session that needs it, every session produces better corrections because the context is richer.

Track Completion Project

Build and deploy a production knowledge-OS MCP server with at least 6 tools, 2 namespaces, HTTP transport, bearer token auth, and L3 health check. Register it in ~/.claude.json and verify it passes the full audit lab (all 16 checks). Document your deployment on the production server (or equivalent persistent machine) with the lsof output showing one PID and the memory_status() output showing your index is populated.

Deliverable: GitHub repo with your server code, Dockerfile, docker-compose.yml, audit-lab-results.md showing all 16 checks passed, and a short write-up of which check revealed the most interesting failure during your audit run.

This track built on the mcp-for-beginners foundation and took you to Stage 4: a production knowledge-OS server with the exact architecture that runs Knox's Semantic Memory Layer. You learned the six production dimensions, the three primitive decision tree, tool surface design, transport and lifecycle, auth and secrets, read/write safety, the split-brain incident, and the audit lab. The next track — Parallel Agent Dispatch and Worktrees — builds on this foundation by showing how production MCP servers fit into multi-agent workflows.