diff --git a/00-overview/postgres-migration-roadmap.md b/00-overview/postgres-migration-roadmap.md index 51c3797..452358e 100644 --- a/00-overview/postgres-migration-roadmap.md +++ b/00-overview/postgres-migration-roadmap.md @@ -533,8 +533,9 @@ - The local client uses the permissive `all_active_users` access mode for testing. Production must use an owner-registered client with HTTPS URLs, a narrower access mode and defined client permissions; role-specific publish policy is still open. -- A full review on 2026-11-19 found 12 issues; all are fixed. Production deployment - must set `GNEXUS_BOOK_MCP_ALLOWED_HOSTS` to include the public MCP hostname, because - FastMCP rejects unknown Host headers with `421`. +- A full review on 2026-11-19 found 12 issues; all are fixed and covered by regression + tests. Production deployment must set `GNEXUS_BOOK_MCP_ALLOWED_HOSTS` to include the + public MCP hostname and `GNEXUS_BOOK_MCP_ALLOWED_ORIGINS` to include its HTTPS origin, + because FastMCP rejects unknown Host headers with `421`. - The next phase is Phase 8: operations hardening, monitoring, documentation, and decommissioning the file write path after the production cutover. diff --git a/30-runbooks/cutover-postgres.md b/30-runbooks/cutover-postgres.md index dc3945b..02c0ebd 100644 --- a/30-runbooks/cutover-postgres.md +++ b/30-runbooks/cutover-postgres.md @@ -68,6 +68,9 @@ - `GET /documents//history` returns imported version 1. - A test changeset can be proposed and applied, with validation passing. - The UI loads documents, history, inventory and status. +- MCP over `/mcp-protocol/` works from the public hostname (no `421 Invalid Host + header`); `GNEXUS_BOOK_MCP_ALLOWED_HOSTS` includes that host and + `GNEXUS_BOOK_MCP_ALLOWED_ORIGINS` includes its HTTPS origin. - A fresh off-host dump exists and its checksum verifies. ## Rollback diff --git a/30-runbooks/local-auth-testing.md b/30-runbooks/local-auth-testing.md index cdf8a5e..5e076e7 100644 --- a/30-runbooks/local-auth-testing.md +++ b/30-runbooks/local-auth-testing.md @@ -109,3 +109,6 @@ - Store client and webhook secrets in gnexus-creds; keep only runtime values in `.env`. - Configure the webhook endpoint without insecure HTTP/private-network overrides. +- Set `GNEXUS_BOOK_MCP_ALLOWED_HOSTS` to the public MCP hostname and + `GNEXUS_BOOK_MCP_ALLOWED_ORIGINS` to its HTTPS origin, otherwise FastMCP rejects + public requests with `421 Invalid Host header`. diff --git a/CLAUDE.md b/CLAUDE.md index 341c752..66ddfd9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -49,7 +49,7 @@ GNEXUS_BOOK_MCP_HOST=0.0.0.0 GNEXUS_BOOK_MCP_PORT=8001 .venv/bin/python -m app.mcp_http ``` -Keys are managed through `/mcp-keys` (session) and `/internal/keys` (service secret, not exposed by nginx); `mcp_tokens` stores only a SHA-256 hash and a tail hint, never plaintext. +Keys are managed through `/mcp-keys` (session) and `/internal/keys` (service secret, blocked by nginx); `mcp_tokens` stores only a SHA-256 hash and a tail hint, never plaintext. Behind nginx, set `GNEXUS_BOOK_MCP_ALLOWED_HOSTS`/`_ORIGINS` to the public hostname and origin or FastMCP returns `421`. ### PostgreSQL read backend (Phase 1) diff --git a/server/.env.example b/server/.env.example index 40aaac1..9bb1162 100644 --- a/server/.env.example +++ b/server/.env.example @@ -16,7 +16,8 @@ # Comma-separated Host values accepted by FastMCP. Add the public hostname # when the MCP endpoint is served behind nginx (e.g. book.gnexus.space). # GNEXUS_BOOK_MCP_ALLOWED_HOSTS=127.0.0.1:*,localhost:*,[::1]:*,book.gnexus.space -# GNEXUS_BOOK_MCP_ALLOWED_ORIGINS=http://127.0.0.1:*,http://localhost:*,http://[::1]:* +# Browser-based MCP clients also need their public HTTPS origin. +# GNEXUS_BOOK_MCP_ALLOWED_ORIGINS=http://127.0.0.1:*,http://localhost:*,http://[::1]:*,https://book.gnexus.space # Internal key-provisioning API (not exposed through nginx) # GNEXUS_BOOK_INTERNAL_KEY_SECRET= # GNEXUS_BOOK_INTERNAL_ALLOWLIST=127.0.0.1,::1 diff --git a/server/README.md b/server/README.md index 872d8f5..846673a 100644 --- a/server/README.md +++ b/server/README.md @@ -150,7 +150,7 @@ - `GNEXUS_BOOK_MCP_TRANSPORT=stdio|sse|streamable-http` - `GNEXUS_BOOK_MCP_HOST`, `GNEXUS_BOOK_MCP_PORT` - `GNEXUS_BOOK_MCP_ALLOWED_HOSTS` — Host values accepted by FastMCP; include the public host behind nginx -- `GNEXUS_BOOK_MCP_ALLOWED_ORIGINS` — allowed Origin values for browser-based clients +- `GNEXUS_BOOK_MCP_ALLOWED_ORIGINS` — allowed Origin values for browser-based clients; include the public HTTPS origin - `GNEXUS_BOOK_MCP_TOKEN` — optional static break-glass token, never a fallback for personal keys - `GNEXUS_BOOK_MCP_REQUEST_RATE_LIMIT` — per-key requests per minute (default 300) - `GNEXUS_BOOK_INTERNAL_KEY_SECRET`, `GNEXUS_BOOK_INTERNAL_ALLOWLIST` — provisioning API protection