MCP Gateway — Fase 1 (KLIP, solo lectura)

Un único servicio seguro que permite al personal autorizado de Energi-Up consultar KLIP en lenguaje natural a través de Claude, sin abrir la aplicación. Estrictamente de solo lectura.

Objetivo de despliegue (PRD Q3, ahora cerrado): <gateway-hostname> -> <gateway-public-ip> (ECS-MCP, ap-southeast-5). Tenga en cuenta que el nombre de host es mcp-gw, no mcp.example.com que suponían los documentos v0.9; el PRD/TSD debe actualizarse para reflejarlo.

Documentos: PRD v0.9 · TSD v0.9 · Guía de implementación · Revisión de diseño · Runbook de despliegue

1. Versiones fijadas (T-1)

La revisión de la especificación MCP y la versión del SDK se fijan aquí. Cuando la documentación del SDK discrepe de los documentos de diseño, el SDK manda — define la API exacta.

Related MCP server: Snowflake MCP Server

2. Estructura

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

Regla de capas (T-3): tools → adapters → core. Nada importa http/ excepto el punto de entrada. Toda la normalización de negocio vive en adapters/klip/normalize.ts, que no importa nada, por lo que se puede probar unitariamente de forma aislada.

3. Autenticación — Downstream Hub OIDC

Los usuarios piloto inician sesión con Downstream Hub (OIDC). El gateway sigue siendo el servidor de autorización con el que habla Claude; el Hub es un paso dentro de su propio flujo /authorize.

Deliberadamente no usamos el ProxyOAuthServerProvider del SDK. El proxy entregaría a Claude un token del Hub, lo que rompería la vinculación de audiencia RFC 8707, daría a Claude ámbitos del Hub más amplios que klip:read, y sacaría la emisión de tokens de nuestro control, de modo que el interruptor de corte S8 ya no podría invalidar las sesiones activas.

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)

La autenticación no es autorización. El Hub demuestra quién es alguien; la tabla users decide si puede usar el conector. La Fase 1 usa una cuenta de servicio KLIP compartida, por lo que todo usuario admitido puede leer todo lo que MCP_READONLY puede leer (revisión H8) — la pertenencia al piloto es el control de acceso a los datos. Una cuenta del Hub que no esté en la lista recibe un 403, y el límite de <= 15 se aplica mediante user:add.

En el flujo se ejecutan dos intercambios PKCE; no los confunda. El code_challenge propio de Claude protege el tramo Claude→gateway (gestionado por el SDK); un verificador separado que el gateway mantiene en el lado del servidor protege el tramo gateway→Hub.

¿Qué cliente del Hub? El propio del gateway — no el de KLIP

Registre un nuevo cliente OIDC para MCP Gateway. No reutilice el registro del Hub de KLIP, aunque KLIP ya esté registrado en el Hub DWS de pruebas.

El Hub solo toca uno de los dos límites de confianza:

Reutilizar el cliente de KLIP rompe el primer límite de forma concreta. El gateway valida el aud del token de ID contra su propio HUB_CLIENT_ID; compartir el id de cliente de KLIP significa que un token de ID emitido durante un inicio de sesión de KLIP sería aceptado por el gateway, que es el patrón de diputado confundido. Los clientes separados son lo que hace distinguibles a las dos partes que confían. También mantiene independientes las listas de permitidos de redirect-URI, los secretos de cliente, los calendarios de rotación, las entradas de auditoría SSO del Hub y los interruptores de desactivación — apagar el cliente del Hub del conector no debe tumbar el inicio de sesión de KLIP.

Nada de esto requiere ningún cambio en el lado de KLIP. K1–K4 no se ven afectados.

Dos instancias del Hub, dos registros

Registre el gateway por separado en cada Hub y empareje cada uno con el KLIP correspondiente:

El emparejamiento se aplica al arrancar, porque equivocarse en una dirección es peligroso, no solo desordenado:

• KLIP_ENV=production + un HUB_ISSUER de pruebas → el gateway se niega a arrancar. De lo contrario, cualquiera que pudiera crear una cuenta en el Hub de pruebas llegaría a datos comerciales reales.

• KLIP_ENV=staging + el HUB_ISSUER de producción → avisa y continúa.

hub:check imprime el emparejamiento que ha detectado, de modo que el corte es verificable:

pairing:       KLIP staging  <->  Hub testing

Qué requiere DWS Hub (no es OIDC estándar)

Según Docs/SSO-TARGET-APP-INTEGRATION.md. Cuatro de estos puntos difieren de los valores predeterminados que asume una biblioteca de cliente OIDC, y tres fallarían directamente:

Por lo tanto, HUB_DISCOVERY_URL se configura explícitamente, HUB_CLIENT_SECRET es opcional, y HUB_TOKEN_BODY tiene como valor predeterminado json con un respaldo de una sola vez a form ante unsupported_grant_type (registrando cuál funcionó, para poder fijarlo).

Configuración

1. Registre el gateway como cliente OIDC en el Hub con la URI de redirección <PUBLIC_URL>/authorize/hub/callback. Es un cliente público — no pida un secreto.

2. Ponga HUB_ISSUER, HUB_DISCOVERY_URL y HUB_CLIENT_ID en /opt/mcp/.env.

3. Verifique antes de que ningún usuario piloto lo intente:

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

   Esto imprime la URI de redirección a registrar, ejecuta el descubrimiento y avisa si el Hub no anuncia PKCE S256. El gateway también sondea el descubrimiento al arrancar y lo informa en /healthz como hub_oidc.

4. Añada usuarios piloto (sin contraseñas — el Hub los autentica):

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

La cuenta de emergencia

Se permite exactamente una cuenta local con contraseña, para usarla cuando el Hub esté caído o mal configurado:

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

Está oculta detrás de una divulgación en la página de inicio de sesión, obliga a cambiar la contraseña en el primer uso, y cada inicio de sesión a través de ella se audita con break_glass: true con severidad alta. Un usuario autenticado por el Hub no puede usar la ruta de contraseña en absoluto, por lo que apagar el Hub no es una forma de recurrir a una contraseña que nadie estableció.

Establece BREAK_GLASS_ENABLED=false una vez que la ruta Hub esté probada en producción para eliminar por completo la superficie de contraseña.

Puerta de grupo opcional — no disponible en DWS Hub

HUB_REQUIRED_GROUP añade una segunda comprobación contra una reclamación de grupos. DWS Hub no emite una (solo anuncia openid profile email), por lo que establecerla rechazaría a todos los usuarios. hub:check avisa si lo haces. La lista de permitidos piloto en la tabla users sigue siendo el control de autorización.

Inicio de sesión iniciado por IdP

El Hub puede enviar a un usuario directamente a una devolución de llamada desde su mosaico de panel. Eso no puede funcionar para un conector: la devolución de llamada existe para completar una solicitud de autorización que Claude inició, por lo que llegar sin una no deja nada contra lo que emitir un código. La puerta de enlace lo detecta y dice "empieza desde Claude en su lugar" en lugar de fallar como "inicio de sesión caducado".

4. Inicio rápido (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

Crea un usuario piloto (funciona con una TTY o entrada canalizada):

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

5. Pruebas

npm test

El Hub simulado es un mini-proveedor OIDC funcional — documento de descubrimiento real, JWKS real, tokens de ID RS256 reales y verificación PKCE en el código de autorización — con cada perilla necesaria para forjar un token malo, porque los casos negativos son el punto.

El fixture KLIP simulado reproduce deliberadamente las peculiaridades del sistema real: kilogramos etiquetados como MT, estados en idiomas mixtos, un incoterm fuera de los cuatro estándar, cantidades nulas, un contrato con entrega excesiva, un limit silenciosamente limitado a 100 y un comentario de contrato que lleva una carga útil de inyección de indicaciones.

6. Despliegue

Procedimiento completo específico del host, con la IP real, el nombre de host y la tabla de grupos de seguridad: 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

CLI de administración — ten en cuenta que esto se ejecuta dentro del contenedor, porque el host instala solo Docker y no tiene 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

Interruptor de emergencia (S8) — objetivo en menos de 5 minutos:

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

Break-glass si el contenedor de la aplicación no está saludable:

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

7. El Apéndice A es una puerta estricta

src/adapters/klip/routes.ts y src/adapters/klip/fields.ts contienen cada ruta KLIP, nombre de parámetro de consulta, límite máximo de tamaño de página, nombre de campo de respuesta y valor de enumeración del que depende el adaptador. Cada entrada está actualmente sin verificar.

La puerta es ejecutable, no administrativa: con KLIP_ENV=production el proceso se niega a iniciar mientras cualquier ruta esté sin verificar. Ejecuta routes:verify contra staging, registra los resultados, establece verified: true por ruta y enums.verified = true.

Dos campos importan más que el resto:

• maxLimit — el limit más grande que KLIP realmente acepta. Si lo limita silenciosamente a 100, un KLIP_PAGE_SIZE de 1000 convierte una página en diez y rompe el objetivo de latencia.

• enums.* — los valores canónicos de estado e incoterm. Cualquier cosa no mapeada se excluye de los totales con una nota de calidad de datos, nunca se asigna un valor predeterminado.

8. Desviaciones de TSD v0.9

Cada una proviene de la revisión de diseño y está comentada en su sitio de llamada.

9. Aún pendiente

• Conciliación del Apéndice A (P1): bloquea la producción, aplicada al inicio.

• K1–K4 del lado KLIP: el rol MCP_READONLY, la cuenta svc-mcp, la regla del grupo de seguridad.

• Sincronización de respaldo fuera del host y una restauración probada: el sidecar solo escribe localmente.

• CIDR de salida corporativos reales en deploy/nginx/mcp.conf y luego habilitar las dos líneas return 403 comentadas.

• Prueba de carga en el NFR de capacidad de 30 usuarios simultáneos.

• Registro del cliente Hub: el propio de la puerta de enlace, primero en el Hub DWS de pruebas: HUB_ISSUER, id y secreto de cliente, con URI de redirección <PUBLIC_URL>/authorize/hub/callback registrada en el lado del Hub. Confirmar los nombres de las reclamaciones de correo electrónico y grupos del Hub y luego ejecutar hub:check. Se necesita un segundo registro, separado, en el Hub de producción en la Etapa 7.

• Decidir si establecer HUB_REQUIRED_GROUP y si establecer BREAK_GLASS_ENABLED=false después de que la ruta del Hub se demuestre en producción.