PoC de MCP con AgentCore + Cognito y cliente público

Prueba de concepto de extremo a extremo que demuestra dos modos de despliegue para un servidor MCP en AgentCore:

1. Standalone — Runtime con autenticación JWT de Cognito directamente (sin gateway)

2. Gateway — Runtime detrás de un AgentCore Gateway con autenticación de entrada PKCE de Cognito y autenticación de salida IAM

Ambos modos utilizan un cliente público de Cognito (sin client_secret) con PKCE para la autenticación de usuarios.

Arquitectura

Modo A: Standalone (Runtime con autenticación JWT directa)

Claude Code / Kiro
    │ PKCE → Cognito Hosted UI → browser
    │ Bearer JWT
    ▼
AgentCore Runtime (CUSTOM_JWT validates token)
    │
    ▼
MCP Server (FastMCP, Python)

Modo B: Gateway (recomendado)

Claude Code / Kiro
    │ PKCE → Cognito Hosted UI → browser
    │ Bearer JWT
    ▼
AgentCore Gateway (CUSTOM_JWT validates token)
    │ SigV4 (gateway IAM role)
    ▼
AgentCore Runtime (AWS_IAM auth)
    │
    ▼
MCP Server (FastMCP, Python)

El modo Gateway proporciona:

• Autenticación centralizada (el gateway gestiona toda la validación JWT)

• Descubrimiento de herramientas y búsqueda semántica en múltiples destinos

• Enrutamiento MCP a nivel de protocolo

• Separación de responsabilidades (el runtime no necesita conocer la autenticación de usuarios)

Estructura del proyecto

.
├── server/
│   ├── cognitopocmcp/              # Runtime deployed via agentcore CLI
│   │   ├── app/cognito_poc_mcp/
│   │   │   └── main.py            # FastMCP server with sample tools
│   │   └── agentcore/             # agentcore CLI config
│   ├── mcp_server.py              # MCP server source (standalone mode)
│   └── requirements.txt
├── src/
│   ├── config.mjs                 # Shared config (project name, region, helpers)
│   ├── auth.mjs                   # PKCE auth module (no secrets!)
│   ├── mcp-server.mjs             # Stdio MCP server (proxy mode)
│   └── test-auth.mjs              # Standalone auth flow test
├── scripts/
│   ├── setup-cognito.mjs          # Creates Cognito pool + public client + user
│   ├── deploy.sh                  # Deploys runtime (standalone mode, with JWT auth)
│   ├── deploy-infrastructure.mjs  # Creates gateway + IAM role + target (gateway mode)
│   ├── test-gateway.mjs           # Tests gateway end-to-end
│   ├── test-deployed.mjs          # Tests standalone runtime end-to-end
│   └── teardown-cognito.mjs       # Deletes all infrastructure
├── .env                           # Generated by setup (Cognito config)
├── .mcp.json                      # Generated by deploy-infra (gateway URL + OAuth)
├── claude-mcp-config.json         # Same as .mcp.json (for copying to Claude/Kiro)
└── package.json

Requisitos previos

# AWS CLI + credentials configured
aws sts get-caller-identity

# Node.js 20+
node --version

# AgentCore CLI
npm install -g @aws/agentcore

# Python 3.10+ (for the MCP server)
python3 --version

Inicio rápido: modo Gateway (recomendado)

Paso 1: Instalar dependencias

npm install

Paso 2: Crear la infraestructura de Cognito

npm run setup

Crea un grupo de usuarios de Cognito con un cliente de aplicación público (sin secreto), un dominio de UI alojado y un usuario de prueba (testuser / TestPass123!). La configuración se guarda en .env.

Paso 3: Desplegar el runtime

npm run deploy-runtime

Despliega el servidor MCP en AgentCore Runtime mediante la CLI agentcore. El runtime utiliza la autenticación IAM predeterminada (el gateway autenticará a los usuarios).

Paso 4: Desplegar el gateway

npm run deploy-infra

Crea:

• Un rol de IAM para el gateway (con permiso para invocar el runtime)

• Un gateway de AgentCore con autenticación de entrada CUSTOM_JWT (PKCE de Cognito)

• Un destino del gateway que apunte al runtime mediante GATEWAY_IAM_ROLE (SigV4)

Actualiza .mcp.json y claude-mcp-config.json con la URL del gateway.

Paso 5: Probar

npm run test-gateway

Autentica mediante Cognito (no interactivo usando el usuario de prueba) y, a continuación:

• Verifica que las solicitudes no autenticadas se rechacen (401)

• Inicializa la sesión MCP

• Muestra las herramientas descubiertas

• Llama a las herramientas (greet_user, add_numbers, get_server_info)

Paso 6: Conectar Claude Code / Kiro

Copia la configuración generada:

# For Kiro — .mcp.json is already in the project root
# For Claude Code
cp claude-mcp-config.json ~/.claude/mcp.json

La configuración tiene este aspecto:

{
  "mcpServers": {
    "cognito-poc": {
      "type": "http",
      "url": "https://<gateway-id>.gateway.bedrock-agentcore.<region>.amazonaws.com/mcp",
      "oauth": {
        "clientId": "<public-client-id>",
        "callbackPort": 8976
      }
    }
  }
}

En la primera invocación de una herramienta, Claude/Kiro abre tu navegador para iniciar sesión en Cognito. A partir de entonces, los tokens se guardan en caché y se actualizan automáticamente.

Inicio rápido: modo Standalone

Si no necesitas un gateway y quieres que el runtime gestione la autenticación JWT directamente:

npm run setup         # Create Cognito pool
npm run deploy        # Deploy runtime with CUSTOM_JWT auth
npm run test-deployed # Test via PKCE (opens browser)

Scripts npm

Herramientas MCP disponibles

El servidor MCP de ejemplo expone:

Cuando se accede a través del gateway, los nombres de las herramientas llevan el prefijo del nombre del destino: mcp-runtime___add_numbers.

Limpieza

npm run teardown

Esto elimina:

• Gateway de AgentCore (destino + destino)

• Rol de IAM del gateway

• Grupos de usuarios de Cognito

• Archivos locales (.env, .mcp.json, claude-mcp-config.json)

El Runtime de AgentCore NO se elimina (se gestiona por separado con la CLI agentcore). Para eliminarlo:

cd server/cognitopocmcp && agentcore destroy

Conceptos clave

Autenticación sin secretos

• Cliente público de Cognito: GenerateSecret: false — no existe secreto de cliente

• PKCE (code_challenge y code_verifier) demuestra la identidad del solicitante sin utilizar un secreto compartido

• Solo el client_id se almacena localmente (un identificador público, no una credencial)

• Los tokens están en memoria con una caducidad de 1 hora y auto-actualización

Autenticación de salida del gateway

El gateway se autentica frente al runtime utilizando su propio rol de IAM (SigV4). Esto evita la complejidad de los flujos OAuth de máquina a máquina entre el gateway y el runtime. El rol de IAM tiene el permiso bedrock-agentcore:* con ámbito limitado al ARN del runtime.

Portabilidad

Todos los valores específicos del entorno se derivan en tiempo de ejecución:

• ID de cuenta de AWS: resuelto mediante STS.GetCallerIdentity

• URL del gateway: se lee desde .mcp.json (generado por deploy-infra)

• ARN del runtime: se lee del estado desplegado de agentcore

• Constantes del proyecto: centralizadas en src/config.mjs

Para desplegar en otra cuenta o región, basta con configurar las credenciales de AWS y volver a ejecutar los pasos de configuración.

Seguridad

Consulta CONTRIBUTING para obtener información sobre cómo informar de problemas de seguridad.

Licencia

Esta librería está bajo la Licencia MIT-0. Consulta el archivo LICENSE.