MCP Overview¶

This document explains the MCP configuration model, namespace structure, and how the gateway runtime connects to AI clients.

Configuration model¶

.mcp.json is the client-facing MCP config and is generated from the Nix flake app mcp-config by just sync-ai. It points AI clients to path-routed endpoints on the local gateway:

Endpoint	Contents
`http://127.0.0.1:8811/mcp`	Unified MCP gateway tool catalog
`http://127.0.0.1:8811/mcp/nixos`	NixOS package and option search

Traefik fronts all HTTP services and routes /mcp and /mcp/nixos to the internal mcp-router service.

There is one client config source of truth and three places it is consumed:

.mcp.json — authoritative source
.vscode/mcp.json — symlink for VS Code GitHub Copilot
opencode.json — generated projection for OpenCode

Run just sync-ai to regenerate all three from the canonical source.

Baseline vs. opt-in servers¶

The baseline enabled set is: bitwarden, github, kagi, nixos, playwright, and wikipedia. These start with every just mcp-up.

All other servers are opt-in. Enable a server by name:

just mcp-enable <server>

Example for podcast production tooling:

just mcp-enable podcast-studio

Example for HashiCorp Vault tooling:

just mcp-enable vault
just bw-vault-credentials-pull

Disable a server:

just mcp-disable <server>

MCP profiles¶

Profiles activate a predefined server set without enabling servers individually.

just mcp-profile-default    # baseline only
just mcp-profile-all        # all servers

After switching profiles, restart the gateway:

just mcp-up

Gateway runtime¶

Command	What it does
`just mcp-up`	Start the baseline gateway stack
`just mcp-down`	Stop the gateway stack
`just mcp-status`	Show container health
`just mcp-logs`	Stream gateway logs
`just mcp-topology`	Show server placement in unified gateway
`just mcp-health`	Verify MCP server wiring and image digests

Gateway membership is declared in arion-compose.nix. Server definitions and pinned image digests are in docker/mcp-gateway/catalogs/agent-hub.yaml. Registry enrollment is in docker/mcp-gateway/registry/all.yaml.

Optional bundle commands:

just mcp-up-ai      # add OpenWebUI, llama.cpp, whisper.cpp, LLM proxy
just mcp-up-dify    # add Dify, Postgres, Redis, MinIO
just stack-up-all   # all bundles

Why `ref: ""` is blank in registry files¶

Registry files use server names as keys and ref: "" to mean "resolve by name against the loaded catalog." The catalog here is docker/mcp-gateway/catalogs/agent-hub.yaml. A blank ref is intentional and not a missing value. A non-blank ref would point to a different named source.

Why NixOS is separate¶

mcp-nixos is an HTTP-native service and runs as its own container routed directly at /mcp/nixos. The unified docker-mcp-gateway endpoint is routed at /mcp.