MCP Gateway — Phase 1 (KLIP, read-only)

A single secure service that lets authorized Energi-Up staff query KLIP in natural language through Claude, without opening the application. Strictly read-only.

Deployment target (PRD Q3, now closed): <gateway-hostname> -> <gateway-public-ip> (ECS-MCP, ap-southeast-5). Note the hostname is mcp-gw, not the mcp.example.com the v0.9 documents assumed; the PRD/TSD should be updated to match.

Documents: PRD v0.9 · TSD v0.9 · Implementation guide · Design review · Deployment runbook

1. Pinned versions (T-1)

The MCP spec revision and SDK version are pinned here. Where the SDK's own docs disagree with the design documents, the SDK wins — it defines the exact API.

Related MCP server: Snowflake MCP Server

2. Layout

src/
  core/       config, logger, db, audit, cache, rateLimit, semaphore, migrate, errors
  adapters/klip/  routes(APPENDIX A) · fields(APPENDIX A) · client(guard) · session · paginate · normalize
  tools/klip/ 9 tool definitions + shared parameter plumbing
  mcp/        server, envelope, runner
  auth/       keys, hub(OIDC RP), users, clients, tokens, provider, loginPage
  http/       app, consent(Hub + break-glass), health, origin, clientIp
migrations/   idempotent SQL (001 schema, 002 Hub OIDC)
deploy/       nginx config, backup sidecar
test/         120 tests + mock KLIP and mock Hub fixtures

Layering rule (T-3): tools → adapters → core. Nothing imports http/ except the entrypoint. All business normalization lives in adapters/klip/normalize.ts, which imports nothing, so it is unit-testable in isolation.

3. Authentication — Downstream Hub OIDC

Pilot users sign in with Downstream Hub (OIDC). The gateway remains the authorization server that Claude talks to; the Hub is one step inside its own /authorize flow.

We deliberately do not use the SDK's ProxyOAuthServerProvider. Proxying would hand Claude a Hub token, which would break the RFC 8707 audience binding, give Claude broader Hub scopes than klip:read, and move token issuance out of our control so the S8 kill switch could no longer invalidate live sessions.

Claude ──/authorize──▶ gateway ──302──▶ Downstream Hub ──302──▶ /authorize/hub/callback
                          │                                              │
                          │        validate id_token (sig/iss/aud/nonce)  │
                          │        check the pilot ALLOWLIST              │
                          ◀──────────────────────────────────────────────┘
                          └──302 code──▶ Claude ──/token──▶ gateway token (klip:read)

Authentication is not authorization. The Hub proves who someone is; the users table decides whether they may use the connector. Phase 1 uses one shared KLIP service account, so every admitted user can read everything MCP_READONLY can read (review H8) — pilot membership is the data-access control. A Hub account that is not on the list gets a 403, and the <= 15 cap is enforced by user:add.

Two PKCE exchanges run in the flow; do not conflate them. Claude's own code_challenge protects the Claude→gateway leg (handled by the SDK); a separate verifier the gateway keeps server-side protects the gateway→Hub leg.

Which Hub client? The gateway's own — not KLIP's

Register a new OIDC client for the MCP Gateway. Do not reuse KLIP's Hub registration, even though KLIP is already registered in the testing DWS Hub.

The Hub only touches one of the two trust boundaries:

Reusing KLIP's client breaks the first boundary in a concrete way. The gateway validates the ID token's aud against its own HUB_CLIENT_ID; sharing KLIP's client id means an ID token minted during a KLIP login would be accepted by the gateway, which is the confused-deputy shape. Separate clients are what make the two relying parties distinguishable. It also keeps the redirect-URI allowlists, client secrets, rotation schedules, Hub SSO audit entries, and disable switches independent — turning the connector's Hub client off must not take KLIP login down.

None of this needs any change on the KLIP side. K1–K4 are unaffected.

Two Hub instances, two registrations

Register the gateway separately in each Hub and pair them with the matching KLIP:

The pairing is enforced at boot, because getting it wrong in one direction is dangerous rather than untidy:

• KLIP_ENV=production + a testing HUB_ISSUER → the gateway refuses to start. Anyone able to create a test-Hub account would otherwise reach real commercial data.

• KLIP_ENV=staging + the production HUB_ISSUER → warns and continues.

hub:check prints the pairing it detected, so the cutover is verifiable:

pairing:       KLIP staging  <->  Hub testing

What DWS Hub requires (it is not vanilla OIDC)

Per Docs/SSO-TARGET-APP-INTEGRATION.md. Four of these differ from the defaults an OIDC client library assumes, and three would fail outright:

Hence HUB_DISCOVERY_URL is configured explicitly, HUB_CLIENT_SECRET is optional, and HUB_TOKEN_BODY defaults to json with a one-shot fallback to form on unsupported_grant_type (logging which worked, so it can be pinned).

Setting it up

1. Register the gateway as an OIDC client in the Hub with redirect URI <PUBLIC_URL>/authorize/hub/callback. It is a public client — do not ask for a secret.

2. Put HUB_ISSUER, HUB_DISCOVERY_URL and HUB_CLIENT_ID in /opt/mcp/.env.

3. Verify before any pilot user tries:

   docker compose exec -T gateway node dist/cli.js hub:check

   This prints the redirect URI to register, runs discovery, and warns if the Hub does not advertise S256 PKCE. The gateway also probes discovery at boot and reports it in /healthz as hub_oidc.

4. Add pilot users (no passwords — the Hub authenticates them):

   docker compose exec -T gateway node dist/cli.js user:add someone@example.com "Their Name"

The break-glass account

Exactly one local password account is permitted, for use when the Hub is down or misconfigured:

docker compose exec -T gateway node dist/cli.js user:add-break-glass it-emergency@example.com

It is hidden behind a disclosure on the login page, forces a password change at first use, and every sign-in through it is audited with break_glass: true at high severity. A Hub-authenticated user cannot use the password path at all, so turning the Hub off is not a way to fall back to a password nobody set.

Set BREAK_GLASS_ENABLED=false once the Hub path is proven in production to remove the password surface entirely.

Optional group gate — not available on DWS Hub

HUB_REQUIRED_GROUP adds a second check against a groups claim. DWS Hub does not issue one (it advertises only openid profile email), so setting it would refuse every user. hub:check warns if you do. The pilot allowlist in the users table remains the authorization control.

IdP-initiated login

The Hub can push a user straight to a callback from its dashboard tile. That cannot work for a connector: the callback exists to complete an authorization request Claude started, so arriving without one leaves nothing to issue a code against. The gateway detects it and says "start from Claude instead" rather than failing as "sign-in expired".

4. Quick start (local)

npm ci
docker run -d --name mcpgw-devdb -e POSTGRES_DB=gateway -e POSTGRES_USER=gateway \
  -e POSTGRES_PASSWORD=devpassword -p 127.0.0.1:55432:5432 postgres:16-alpine
cp .env.example .env.dev   # then edit: PUBLIC_URL=http://localhost:8787, DATABASE_URL=...55432...
npx tsx test/fixtures/mockKlip.ts 5099 &      # mock KLIP, behaves like the real one
set -a; . ./.env.dev; set +a
npm run migrate
npx tsx src/index.ts

Create a pilot user (works with a TTY or piped input):

printf 'a-strong-password\na-strong-password\n' | npx tsx src/cli.ts user:add you@example.com "Your Name"

5. Tests

npm test

The mock Hub is a working mini-OIDC provider — real discovery document, real JWKS, real RS256 ID tokens, and PKCE verification on the authorization code — with every knob needed to forge a bad token, because the negative cases are the point.

The mock KLIP fixture deliberately reproduces the real system's quirks: kilograms labelled MT, mixed-language statuses, an incoterm outside the standard four, null quantities, an over-delivered contract, a limit silently clamped to 100, and a contract remark carrying a prompt-injection payload.

6. Deploy

Full host-specific procedure, with the real IP, hostname and security-group table: deploy/RUNBOOK.md.

# on ECS-MCP
cd /opt/mcp && git pull
docker compose build gateway && docker compose up -d
curl -fsS http://127.0.0.1:8787/healthz

Admin CLI — note this runs inside the container, because the host installs Docker only and has no Node.js:

docker compose exec -T gateway node dist/cli.js user:list
docker compose exec -T gateway node dist/cli.js audit:summary --days 7
docker compose exec -T gateway node dist/cli.js audit:export --from 2026-08-01 --to 2026-09-01 --out /tmp/audit.csv
docker compose exec -T gateway node dist/cli.js routes:verify        # probes KLIP, reports Appendix A gaps

Kill switch (S8) — target under 5 minutes:

docker compose exec -T gateway node dist/cli.js tokens:revoke-all --reason "incident 2026-xx"
docker compose stop gateway

Break-glass if the app container is unhealthy:

docker compose exec -T db psql -U gateway -d gateway -c "UPDATE oauth_tokens SET revoked_at=now() WHERE revoked_at IS NULL;"

7. Appendix A is a hard gate

src/adapters/klip/routes.ts and src/adapters/klip/fields.ts hold every KLIP path, query-parameter name, page-size ceiling, response field name and enum value the adapter depends on. Every entry is currently unverified.

The gate is executable, not clerical: with KLIP_ENV=production the process refuses to start while any route is unverified. Run routes:verify against staging, record the results, set verified: true per route and enums.verified = true.

Two fields matter more than the rest:

• maxLimit — the largest limit KLIP actually accepts. If it silently clamps to 100, a KLIP_PAGE_SIZE of 1000 turns one page into ten and breaks the latency target.

• enums.* — the canonical status and incoterm values. Anything unmapped is excluded from totals with a data-quality note, never defaulted.

8. Deviations from TSD v0.9

Each one comes from the design review and is commented at its call site.

9. Still outstanding

• Appendix A reconciliation (P1) — blocks production, enforced at startup.

• KLIP-side K1–K4 — the MCP_READONLY role, svc-mcp account, security-group rule.

• Off-host backup sync and a tested restore — the sidecar writes locally only.

• Real corporate egress CIDRs in deploy/nginx/mcp.conf, then enable the two commented return 403 lines.

• Load test at the 30-concurrent-user capacity NFR.

• Hub client registration — the gateway's own, in the testing DWS Hub first: HUB_ISSUER, client id and secret, with redirect URI <PUBLIC_URL>/authorize/hub/callback registered Hub-side. Confirm the Hub's email and groups claim names, then run hub:check. A second, separate registration in the production Hub is needed at Stage 7.

• Decide whether to set HUB_REQUIRED_GROUP, and whether to turn BREAK_GLASS_ENABLED=false after the Hub path is proven in production.