feat: add MCP server to Docker Compose files (#1208)

* feat: add MCP server to Docker Compose files

Add mcp-server service to dev and demo stacks. Dev stack builds from
source, exposes port 8091, and connects to meridian:50051 with a dev
API key. Demo stack pulls a versioned image, requires MCP_API_KEY, and
runs internal-only (proxied via Caddy).

* fix: use correct MERIDIAN_API_KEY env var in demo compose

The MCP server reads MERIDIAN_API_KEY (not MCP_API_KEY) as defined in
services/mcp-server/internal/auth/auth.go. Align demo compose with
dev compose and the application's expected env var name.

* fix: address CodeRabbit feedback on demo compose mcp-server config

- Promote MCP_BASE_URL to fail-fast (:?) to prevent silent SSE
  misconfiguration; the server needs its own public URL for SSE
  handshakes and OAuth redirect URIs
- Fix Caddyfile comment to reference actual endpoints (/sse, /message)
  instead of incorrect /mcp/* wildcard

* docs: clarify OAuth env vars required when MCP_OAUTH_ENABLED=true

Add inline comments to MCP_OAUTH_CLIENT_ID and MCP_OAUTH_REDIRECT_URI
in the demo compose to prevent silent misconfiguration when OAuth is
enabled without the necessary companion variables.

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

deploy/demo/docker-compose.yml

@@ -1,10 +1,11 @@
 # Meridian demo deployment stack
 #
 # Services:
-#   postgres   - PostgreSQL 16 (internal only, not exposed to host)
-#   dex        - Lightweight OIDC identity provider (~20MB RAM)
-#   meridian   - Unified binary; starts after postgres + dex are healthy
-#   caddy      - Reverse proxy; exposes 80/443, terminates TLS via Cloudflare Origin Certificate
+#   postgres    - PostgreSQL 16 (internal only, not exposed to host)
+#   dex         - Lightweight OIDC identity provider (~20MB RAM)
+#   meridian    - Unified binary; starts after postgres + dex are healthy
+#   caddy       - Reverse proxy; exposes 80/443, terminates TLS via Cloudflare Origin Certificate
+#   mcp-server  - MCP server for AI integration (internal, proxied via Caddy)
 #
 # Usage:
 #   cp deploy/demo/.env.demo.example /opt/meridian/.env
@@ -108,6 +109,34 @@ services:
     # and retries upstream connections itself during meridian startup.
     # Not exposed to host — accessed only by caddy on the internal network
 
+  mcp-server:
+    image: ${MCP_SERVER_IMAGE:-ghcr.io/meridianhub/mcp-server:demo}
+    restart: unless-stopped
+    depends_on:
+      meridian:
+        condition: service_started
+    environment:
+      # --- MCP Transport ---
+      MCP_TRANSPORT: sse
+      MCP_SSE_PORT: "8090"
+      MCP_SERVER_NAME: ${MCP_SERVER_NAME:-meridian-mcp}
+      MCP_BASE_URL: ${MCP_BASE_URL:?MCP_BASE_URL must be set in the env file (e.g. https://your-domain)}
+
+      # --- Meridian API ---
+      MERIDIAN_API_URL: meridian:50051
+      MERIDIAN_API_KEY: ${MERIDIAN_API_KEY:?MERIDIAN_API_KEY must be set in the env file}
+
+      # --- Application ---
+      LOG_LEVEL: ${LOG_LEVEL:-info}
+
+      # --- OAuth (optional) ---
+      MCP_OAUTH_ENABLED: ${MCP_OAUTH_ENABLED:-false}
+      MCP_OAUTH_CLIENT_ID: ${MCP_OAUTH_CLIENT_ID:-}      # required when MCP_OAUTH_ENABLED=true
+      MCP_OAUTH_REDIRECT_URI: ${MCP_OAUTH_REDIRECT_URI:-} # required when MCP_OAUTH_ENABLED=true
+    # Not exposed to host — accessed only by caddy on the internal network
+    # Add to Caddyfile: reverse_proxy /sse mcp-server:8090
+    #                   reverse_proxy /message mcp-server:8090
+
   caddy:
     image: caddy:2-alpine
     restart: unless-stopped

deploy/dev/docker-compose.yml

@@ -6,6 +6,7 @@
 #   meridian     - Unified binary; starts after migrations complete
 #   seed         - One-shot seed runner; creates dev tenant and applies manifest (idempotent)
 #   frontend     - Vite dev server with HMR on port 5173
+#   mcp-server   - MCP (Model Context Protocol) server for AI integration on port 8091
 #
 # Usage:
 #   docker compose -f deploy/dev/docker-compose.yml up
@@ -16,6 +17,7 @@
 #   50051 - meridian gRPC
 #   8090  - meridian HTTP gateway
 #   5173  - frontend (Vite dev server)
+#   8091  - mcp-server SSE endpoint
 
 services:
   cockroachdb:
@@ -99,6 +101,25 @@ services:
     environment:
       VITE_API_BASE_URL: "http://localhost:8090"
 
+  mcp-server:
+    build:
+      context: ../..
+      dockerfile: services/mcp-server/cmd/Dockerfile
+    depends_on:
+      meridian:
+        condition: service_started
+    ports:
+      - "127.0.0.1:8091:8090"
+    environment:
+      LOG_LEVEL: info
+      MCP_TRANSPORT: sse
+      MCP_SSE_PORT: "8090"
+      MCP_SERVER_NAME: meridian-mcp
+      MCP_BASE_URL: http://localhost:8091
+      MERIDIAN_API_URL: meridian:50051
+      MERIDIAN_API_KEY: dev-key
+      MCP_OAUTH_ENABLED: "false"
+
 volumes:
   cockroachdb_data:
   frontend_node_modules: