OpenAPI: el contrato de la API al alcance del agente

La regla: el MCP solo lee

El MCP de OpenAPI (@ivotoby/openapi-mcp-server) sirve para descubrir qué endpoints existen y qué piden y devuelven. En este repo no ejecuta requests autenticadas. Para eso hay dos piezas más, cada una con un solo trabajo:

El MCP no tiene un modo de solo lectura, así que la protección es otra: no recibe ninguna credencial. Si alguien intenta ejecutar con él, la API responde 401, y ese 401 es la señal de usar curl. Mantener el token fuera del MCP evita además dos problemas conocidos: un header fijo no se refresca cuando el token caduca, y choca con un parámetro Authorization declarado en el spec (Cannot override authentication header).

Configurar el MCP

El server openapi ya está declarado en .mcp.json, opencode.jsonc y .codex/config.toml, igual en los tres: arranca detrás del loader de .env, que lee de .env solo las dos variables de su --filter. Así queda en .mcp.json (las versiones están fijadas ahí):

"openapi": {
  "command": "bunx",
  "args": [
    "-p", "varlock@<pin>", "varlock", "run", "--no-redact-stdout",
    "--inject", "vars", "--filter", "API_BASE_URL,OPENAPI_SPEC_PATH", "--",
    "bunx", "-y", "@ivotoby/openapi-mcp-server", "--tools", "dynamic"
  ]
}

No tiene API_HEADERS ni token, y no debe tenerlos. Lo único que configuras son dos variables en .env:

Como con cualquier MCP, las variables se leen al arrancar la sesión. Abre el agente como siempre (claude, opencode o codex, o su app de escritorio) y reinícialo si cambias alguna de las dos.

Para comprobar que funciona, pregunta al agente qué endpoints tiene la API. Debería llamar a list-api-endpoints y devolver la lista.

Desde una app de escritorio

Este MCP es el más delicado de todos al abrir el harness desde el Dock o el menú de inicio: si al arrancar le falta API_BASE_URL, OPENAPI_SPEC_PATH o el propio spec, se cierra antes del handshake y el harness solo muestra un server caído. DBHub, en cambio, lee .env por su cuenta y arranca igual, por eso uno puede fallar mientras el otro parece bien.

Claude Code, OpenCode y Codex

Los tres arrancan este MCP con varlock run --no-redact-stdout ... -- delante, así que lee .env aunque la app no tenga variables de entorno. Hace falta bun install una vez (el loader es la dependencia varlock) y un .env con valores en la raíz del proyecto. Si cambias .env, reinicia la app.

Codex Desktop

En un worktree que crea la app, .env y api/openapi.json llegan por el .worktreeinclude del repo, y la app corre bun run worktree:provision (dependencias incluidas) desde .codex/environments/environment.toml.

El spec

api/openapi.json está en .gitignore, así que un worktree nuevo no lo trae. bun run setup:doctor avisa si el archivo no existe o si la URL no responde, y bun run api:sync lo vuelve a crear.

Las tres herramientas

Con --tools dynamic el MCP no crea una herramienta por endpoint. Expone exactamente tres herramientas genéricas:

Obtener el token

bun run api:login solo obtiene el token. Se autentica con las credenciales del entorno y rol que le pidas (las lee de .env con los nombres que declara config/variables.ts, por ejemplo STAGING_USER_EMAIL y STAGING_USER_PASSWORD; si faltan, falla nombrándolas) y guarda el resultado en disco:

bun run api:login                       # entorno activo (TEST_ENV), rol user
bun run api:login staging               # entorno explícito
bun run api:login staging --role admin  # otro rol
bun run api:login staging --profile W1  # juego de tokens aislado en .auth/profiles/W1/
bun run api:login --help                # opciones, rutas y variables que necesita

La variable del token va en mayúsculas: API_TOKEN_ADMIN_STAGING, API_TOKEN_USER_LOCAL. Varios roles y entornos conviven en el mismo archivo. Todo .auth/ está en .gitignore, nada se escribe en .env y no hace falta reiniciar la sesión después del login.

Si tu backend se autentica de otra forma, el archivo que se adapta es scripts/api-login.project.ts. El resto de la CLI vive en scripts/lib/api-login-core.ts y llega con las actualizaciones del repo.

Ejecutar con curl

Cada llamada Bash del agente abre una shell nueva, así que el token no sobrevive de una llamada a otra. Se hace source del archivo en la misma llamada que el curl:

source .auth/tokens.env && \
curl -s -H "Authorization: Bearer $API_TOKEN_ADMIN_STAGING" \
  "$API_BASE_URL/products"

Para probar aislamiento entre roles (por ejemplo, que un usuario no vea datos de otro tenant) basta con usar variables distintas del mismo archivo: $API_TOKEN_ADMIN_STAGING frente a $API_TOKEN_USER_STAGING.

Cuando el token expira

Antes de reutilizar un token, mira si sigue vigente: createdAt más expiresIn en .auth/tokens.json.

jq -r '.ADMIN_STAGING | (.createdAt + " +" + (.expiresIn|tostring) + "s")' .auth/tokens.json

Si ya pasó, o una request devuelve 401, vuelve a ejecutar bun run api:login <env> --role <role> y repite. Un 401 por token caducado no es un bug.

Schema de dev, entorno de staging

El schema que lee el MCP suele ser el de dev, la versión más reciente. El entorno que estás probando (staging, por ejemplo) puede ir por detrás, así que un endpoint o un campo que aparece en el schema quizá todavía no existe en ese servidor. Ante un 4xx inesperado, un campo que falta o una respuesta con otra forma, sospecha primero de esta diferencia y compruébalo contra el entorno real antes de reportar un bug.

Tipos para los tests automatizados

bun run api:sync descarga el spec (de una URL, de un repo de GitHub o de un archivo local) y genera los tipos TypeScript en api/openapi-types.ts. Las facades de api/schemas/ los reexportan para que los tests los importen.

bun run api:sync                                          # interactivo
bun run api:sync --url http://localhost:3000/api/openapi  # desde una URL
bun run api:sync --file ./path/to/spec.json               # desde un archivo local
bun run api:sync --config                                 # con la configuración guardada

Los tipos se comprueban al compilar, no en ejecución. Un tipo detecta un test que lee un campo que el contrato no tiene, pero no detecta una API que devuelve otra forma. La forma que te importa se valida con asserts explícitos en el test.

Qué herramienta para qué

Los patrones de API testing con KATA están en .agents/skills/test-automation/references/api-patterns.md.

Problemas frecuentes