Demo en capas de API de gestión de usuarios + MCP

Pequeña demo hecha con Node.js (solo JS). Es una muestra para presentaciones que muestra por capas la configuración de «ofrecer la misma API tanto a usuarios humanos como a agentes de IA, con autenticación y alcance de exposición distintos para cada uno, y cubrir el lado de la IA con un servidor MCP (capa de descripción de API)».

La base del diseño es el MCP en producción de spx-learning-square (spx-learning-square/mcp/, 65 herramientas, distribución .mcpb). Esta demo reduce esa idea a la configuración mínima.

Visión general

 人間ユーザー ──ログイン──▶ セッショントークン ─┐
                                                  │ Authorization: Bearer
 AI (Claude) ──▶ MCP サーバー ──PAT──────────────┤
              （mcp/index.mjs                     ▼
                = API 説明層）          ┌─────────────────────────┐
                                        │ API サーバー (Express)  │
                                        │  認証層（2 系統）       │
                                        │  エージェント公開       │
                                        │  レジストリ             │
                                        │  controller             │
                                        │  service                │
                                        │  repository（メモリ）   │
                                        └─────────────────────────┘

Related MCP server: MCP CRUD Tools

Estructura de capas

Matriz de permisos (la clave de la demo)

Las operaciones destructivas (actualizar y eliminar) son exclusivas de humanos porque no se registran en el registro. El punto clave es que «qué se le permite a la IA» se puede ver de un vistazo en un único archivo, agentRegistry.mjs.

Cómo ejecutarlo

1. Servidor de API

npm install
npm run api          # http://localhost:3000

Para arrancarlo con Docker (solo la API se conteneriza):

npm run docker       # = docker compose up --build → http://localhost:3000

La capa MCP (mcp/index.mjs) no se mete en el contenedor. Como Claude Desktop / Claude Code la inician con stdio en la máquina del usuario, la distribución se hace con .mcpb, no con Docker. Este también es un punto de la presentación: la API está en el lado del servidor (Docker/ECS), el MCP en el lado del cliente (.mcpb), y las unidades de despliegue están separadas.

Flujo del usuario humano (inicio de sesión → CRUD):

# ログイン（デモ: alice / demo）
TOKEN=$(curl -s -X POST localhost:3000/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"login_id":"alice","password":"demo"}' | node -p 'JSON.parse(require("fs").readFileSync(0)).data.token')

curl -s localhost:3000/api/users -H "Authorization: Bearer $TOKEN"          # 一覧
curl -s -X DELETE localhost:3000/api/users/3 -H "Authorization: Bearer $TOKEN"  # 削除も OK

Flujo del agente de IA (PAT, clave predeterminada agent-demo-key):

curl -s localhost:3000/api/users -H "Authorization: Bearer agent-demo-key"       # ✅ 200
curl -s localhost:3000/api/agent/apis -H "Authorization: Bearer agent-demo-key"  # ✅ 公開一覧
curl -s -X DELETE localhost:3000/api/users/2 \
  -H "Authorization: Bearer agent-demo-key"                                       # ❌ 403 user_only

Hay 2 tipos de códigos de error: user_only = API con guarda exclusiva de humanos (actualizar y eliminar), agent_not_allowed = API cuya guarda es forAgent pero que no está registrada en el registro.

2. Servidor MCP (capa de descripción de API)

UI de depuración (MCP Inspector):

npm run inspect

Registro en Claude Code:

claude mcp add users-demo -- node /Users/d.bui/Documents/project/mcp-from-scratch/mcp/index.mjs

Ejemplos de conversación: «enséñame la lista de usuarios» → list_users, «registra a un nuevo miembro» → create_user, «elimina al número 3» → no hay herramienta, así que se indica la pantalla de administración (indicado en instructions).

3. Pruebas E2E (golpear el MCP «en lugar de Claude»)

npm test             # test/mcp-client.test.mjs

Con el cliente del SDK de MCP se hace una conexión stdio a mcp/index.mjs (la misma ruta que Claude), y se verifica automáticamente: arranque de la API → todas las herramientas + recursos + casos anómalos (ID inexistente / email duplicado / violación de esquema). También sirve para la demo en vivo durante la presentación.

4. Distribución con .mcpb para Claude Desktop

.mcpb = manifest.json + código comprimido en zip como Desktop Extension. Se instala con doble clic, y el usuario no necesita instalar Node ni editar archivos de configuración. La URL de la API y la clave de acceso se inyectan en env desde user_config (el formulario de instalación) (las claves con sensitive: true se guardan en el llavero del SO).

npx @anthropic-ai/mcpb validate manifest.json
npm run pack         # → dist/users-mcp-demo.mcpb（node_modules ごと同梱）

El artefacto de compilación se genera en dist/ (fuera del control de git). Gracias a .mcpbignore, el código de la API y los archivos relacionados con Docker no se incluyen en la extensión: en el paquete solo entran manifest.json + mcp/ + node_modules.

Diapositivas de la presentación

Si abres slides/index.html en el navegador, puedes presentar directamente (navegación con las teclas ← →, 14 diapositivas, funciona sin conexión). La estructura es: visión general → capturas de código de cada capa → matriz de permisos → distribución → procedimiento de la demo → aprendizajes de producción.

Puntos de la presentación (desde la operación real de spx-learning-square)

• La capa MCP no tiene permisos. No toca la base de datos; solo llama a la API REST con el PAT. La comprobación de permisos y la validación están todas en un único lugar del lado de la API: aunque el MCP se rompa, no ocurren accidentes que la UI no pueda hacer.

• La autenticación está separada en 2 vías. Humanos = inicio de sesión + sesión, IA = PAT emitido previamente. Si el origen del token es distinto, la revocación, la auditoría y la limitación de tasa también se pueden diseñar por separado.

• La exposición a la IA es «por registro explícito». Si se abre por prefijo de ruta, se corre el riesgo de abrir sin querer también las API sensibles vecinas (lección que casi ocurre de verdad). El registro funciona además directamente como «especificación de API para IA».

• El texto de descripción de las herramientas es una instrucción para el modelo. Escribir reglas operativas como «no adivines el ID, resuélvelo con list_users» o «para eliminar, indica la pantalla de administración» en description / instructions permite controlar el comportamiento de la IA con texto, no con código.

• Los errores no se lanzan con throw, se devuelven con isError + un code legible por máquina. El modelo puede leer el code y recuperarse por sí mismo (email_taken → proponer otra opción, etc.).

• stdout es exclusivo para JSON-RPC. En un servidor stdio, usar console.log rompe la comunicación. Los registros deben ir siempre con console.error.

Referencias

• Especificación y documentación de MCP: https://modelcontextprotocol.io

• SDK de TypeScript/JS: https://github.com/modelcontextprotocol/typescript-sdk

• MCPB (especificación de manifest + CLI): https://github.com/anthropics/mcpb

• Implementación en producción: ../spx-learning-square/mcp/ (bundle de 1 archivo con esbuild, etiqueta de entorno incrustada, configuración en la que el backend genera dinámicamente el .mcpb)