REST API y MCP

Usa REST y MCP cuando un flujo de trabajo de Opfield deba ser repetible, atribuible e independiente del navegador de un operador. Un flujo de trabajo está terminado cuando el recurso alcanza el estado previsto, no cuando se acepta la petición HTTP o vuelve la llamada a la herramienta.

La REST API expone operaciones documentadas sobre los recursos con autenticación por sesión, token de API u OAuth según corresponda. MCP remoto ofrece herramientas orientadas a tareas sobre los mismos ámbitos, validaciones, derechos del plan y rastro de auditoría.

La automatización debe:

usar una identidad dedicada con el mínimo privilegio;
tratar un 202 o la creación de un Task como trabajo aceptado y consultar después el estado duradero;
reintentar solo las operaciones idempotentes, enviar una Idempotency-Key con las creaciones que la aceptan, o usar el contrato de reintento de la operación;
tratar por separado los fallos 401, 403, 409, 422 y de nodo desconectado;
evitar analizar el texto de la interfaz cuando existe un campo estructurado en la API;
registrar los ID de recursos y de peticiones sin registrar secretos.

Usa el documento OpenAPI que sirve la instancia de Opfield en ejecución para ver los esquemas exactos de las peticiones y las respuestas. La versión del esquema debe coincidir con la instancia que se automatiza; no copies cuerpos de petición de otra versión. Las guías del producto describen el orden necesario de los recursos y las consecuencias operativas que los esquemas por sí solos no pueden recoger.

Autenticación y descubrimiento

Elige una sesión, un token de API o un cliente OAuth según quién haga la llamada. Los clientes de MCP remoto se autorizan mediante OAuth y descubren herramientas orientadas a tareas filtradas por los mismos ámbitos y el mismo estado del producto. Que una herramienta exista no demuestra que se vaya a admitir un cambio concreto sobre un recurso.

Empieza la automatización leyendo el recurso de destino y el estado de sus capacidades. Resuelve ID estables en lugar de extraer nombres de la interfaz. Mantén separados la URL base, el token y el entorno para que un script de desarrollo no pueda apuntar a producción por accidente.

Averigua a qué puede acceder quien llama

El acceso limitado a carpetas, nodos o recursos individuales es normal para la automatización y los agentes. Lee el resumen de acceso de quien llama antes de crear recursos, y siempre que una lista vuelva vacía o se rechace una creación en la raíz:

REST: GET /api/auth/me/access, con una sesión, un token de API o un token OAuth.
MCP y AI Workspace: la herramienta get_my_access, opcionalmente con un area como docker_containers o routes.
Recurso de MCP: opfield://access.

El resumen agrupa el acceso por área del producto. Para cada área indica si el acceso es broad o limited, enumera las carpetas concedidas (ID, nombre y ruta), los nodos, las cuentas y los recursos con las acciones permitidas en cada uno, e indica dónde puede crear quien llama: create.atRoot, create.folders y create.nodes, con una indicación howTo. El objeto principal indica el tipo de credencial (session, api-token, oauth-token, mcp o assistant). Solo una sesión del navegador y AI Workspace reciben además el ID, el nombre, el correo y el grupo de permisos del usuario; los tokens de API, los tokens OAuth y los clientes MCP solo reciben principal: { credential, boundedByOwner: true }, porque su acceso nunca supera el acceso actual del propietario. Cuando una conexión MCP está limitada, Opfield añade también una versión breve del resumen a las instrucciones del servidor MCP en el momento de conectar.

El área apps solo enumera los ámbitos de apps. Una app que quien llama solo ve a través de sus recursos no aparece allí; list_apps y get_app la devuelven con access: "members". Consulta Quién ve una app.

Trabaja dentro de las concesiones indicadas:

Los endpoints y las herramientas de listado solo devuelven aquello a lo que puede acceder quien llama; una lista vacía no es una denegación.
list_resource_folders muestra todas las carpetas sobre las que quien llama tiene alguna concesión, incluidas las vacías, con access.actions y access.canCreate.
Una creación sin folderId apunta a la raíz. Pasa folderId, y nodeId cuando la operación lo admite, si el acceso de creación está limitado.
Un rechazo a quien tiene un acceso limitado (una creación en la raíz o una lectura de un recurso fuera de sus concesiones) indica las carpetas, los nodos y los recursos que puede usar y dice que pase folderId, tanto en las respuestas de REST como en los errores de las herramientas de MCP y de AI Workspace. Considera que falta un permiso solo cuando el resumen no muestra ninguna concesión para la acción en ninguna parte.

Conecta Codex o Claude Code mediante MCP

Opfield expone su servidor MCP remoto autenticado en:

https://opfield.example.com/api/mcp

Sustituye opfield.example.com por el nombre de host público canónico de tu instalación de Opfield. Usa el mismo origen HTTPS que usan los operadores para abrir Opfield. No añadas otro /mcp ni apuntes el cliente a la raíz de la REST API.

Una vez conectado, el cliente puede descubrir las herramientas de Opfield y realizar solo las operaciones permitidas al usuario que ha iniciado sesión. MCP no concede acceso de administrador ni elude los ámbitos de recursos, los derechos del plan, las confirmaciones ni el registro de auditoría.

Prepara Opfield

Un administrador completa estos pasos una sola vez:

Abre Settings, selecciona Features y busca OAuth and MCP access.
Activa Enable MCP server.
Mantén activado Extended MCP compatibility para los clientes normales. Desactívalo solo cuando un cliente cargue todo el catálogo de herramientas en su contexto y no pueda gestionar su tamaño.
Deja desactivado OAuth extended callback compatibility para Codex y Claude Code. Sus callbacks locales de loopback funcionan con la política predeterminada, que es más segura.
Concede al usuario que se conecta Use MCP (mcp:use) más los ámbitos habituales de los recursos que ese cliente puede leer o cambiar.

El usuario también debe poder iniciar sesión en Opfield en un navegador. Si la conexión funciona pero falta una herramienta o un recurso, revisa la pertenencia a grupos y los ámbitos de recursos en lugar de ampliar la política de callbacks de OAuth.

Conecta Codex

Añade Opfield, completa el inicio de sesión con OAuth y verifica la conexión:

codex mcp add opfield --url https://opfield.example.com/api/mcp
codex mcp login opfield
codex mcp list

El comando de inicio de sesión abre Opfield en tu navegador. Inicia sesión como el usuario de Opfield previsto, revisa el acceso solicitado y apruébalo. Codex guarda la credencial OAuth resultante; no creas ni pegas ningún token de API.

En la aplicación de escritorio de Codex o en la extensión del IDE, puedes añadir en su lugar un servidor MCP Streamable HTTP con la misma URL y seleccionar Authenticate. La aplicación de escritorio, la CLI y la extensión del IDE comparten la configuración de MCP de Codex.

Conecta Claude Code

Añade Opfield como servidor HTTP remoto para tu cuenta de usuario:

claude mcp add --transport http opfield --scope user https://opfield.example.com/api/mcp
claude mcp login opfield
claude mcp get opfield

También puedes abrir una sesión interactiva de Claude Code, introducir /mcp, seleccionar opfield y completar la autenticación en el navegador. Usa --scope project en lugar de --scope user solo cuando el repositorio deba compartir la definición del servidor mediante .mcp.json; cada desarrollador sigue iniciando sesión con su propia cuenta de Opfield.

Cómo funciona el flujo de OAuth

No necesitas registrar a mano un cliente OAuth para Codex ni para Claude Code:

el cliente contacta con /api/mcp y recibe la información de descubrimiento de OAuth de Opfield;
el cliente se registra e inicia Authorization Code con PKCE;
Opfield abre una pantalla de inicio de sesión y de consentimiento en el navegador;
el usuario aprueba un acceso limitado por sus ámbitos actuales de Opfield y puede restringirlo a carpetas, entornos de apps o recursos, por ejemplo desde la cabecera de una sección de ámbitos que muestra Everywhere en Review N scopes; consulta Restringe los tokens y las concesiones OAuth;
Opfield emite un token de acceso OAuth para el recurso MCP;
el cliente guarda esa credencial y la envía a /api/mcp en las peticiones posteriores.

Opfield solo acepta tokens de acceso OAuth emitidos para su recurso MCP. Se rechazan las cookies del navegador, los tokens de API gw_ normales, los tokens de logging gwl_ y los tokens de Opfield Inference gwi_. El servidor vuelve a comprobar los ámbitos actuales del usuario y mcp:use, de modo que retirar el acceso detiene las operaciones MCP futuras aunque el cliente haya descubierto antes las herramientas.

Verifica la conexión

Empieza con una petición de solo lectura:

List the Opfield nodes I can access and summarize their current status. Do not change anything.

Confirma que el cliente muestra opfield como conectado, que solo son visibles los recursos esperados, que una lectura tiene éxito, que se deniega una acción fuera de los ámbitos del usuario y que Opfield atribuye la llamada al usuario esperado en el registro de auditoría.

Solución de problemas de la conexión MCP

El endpoint devuelve 404: activa Settings → Features → OAuth and MCP access → Enable MCP server y verifica que la URL termina en /api/mcp.
El cliente requiere autenticación: ejecuta codex mcp login opfield o claude mcp login opfield. En un cliente interactivo, usa /mcp.
El inicio de sesión funciona, pero Opfield devuelve 403: la cuenta necesita mcp:use y al menos un ámbito de recurso efectivo. Una concesión limitada a una carpeta solo ve los recursos de esa carpeta; crear en otro sitio se deniega. Pide al agente que llame a get_my_access y que cree en una de las carpetas que enumera; consulta Averigua a qué puede acceder quien llama.
Un cliente envía un nombre de ámbito que ya no existe: Opfield sigue aceptando los nombres de ámbitos retirados y concede sus sustitutos.
El cliente agota su contexto con demasiadas herramientas: desactiva Extended MCP compatibility para usar el catálogo inicial compacto y el descubrimiento por categorías.
Opfield rechaza el callback de OAuth: actualiza primero el cliente y vuelve a intentarlo. Los callbacks de loopback normales de Codex y Claude Code no requieren OAuth extended callback compatibility.
Una conexión guardada ha dejado de funcionar: comprueba si han cambiado la autorización OAuth, mcp:use, los ámbitos de recursos o la URL canónica de Opfield. Vuelve a autenticarte en lugar de sustituirla por un token de API normal.

Operaciones duraderas

Muchos cambios de infraestructura devuelven un Task o una operación aceptados en lugar de un resultado completado:

envía la petición validada;
guarda los ID devueltos del recurso, del Task, de la operación y de la petición;
consulta o suscríbete al estado duradero de la operación;
inspecciona los detalles estructurados de los fallos;
verifica de forma independiente el estado resultante del recurso;
reintenta solo según el contrato de idempotencia de la operación.

No conviertas directamente un tiempo de espera agotado del transporte en una segunda petición de creación o eliminación. La primera petición puede haber llegado al daemon propietario y estar esperando la conciliación. Una creación enviada a un endpoint que acepta una Idempotency-Key es la excepción: reinténtala con la misma clave.

Reintentos seguros con Idempotency-Key

Algunos endpoints de creación aceptan una cabecera Idempotency-Key opcional de 1 a 255 caracteres ASCII imprimibles, por ejemplo un UUID. El documento OpenAPI indica la cabecera exactamente en estas operaciones:

Docker: crear y duplicar contenedores, y crear Deployments, Compose Projects, recursos a partir de un origen Git, volúmenes, redes y registros;
Tráfico entrante y certificados: Routes (POST /api/proxy-hosts), carpetas de Routes, dominios, certificados ACME y autoridades de certificación raíz e intermedias;
Bases de datos y almacenamiento: conexiones de bases de datos, bases de datos gestionadas, conexiones de almacenamiento y almacenamiento gestionado;
Otros: Page Projects, reglas de alerta y destinos SIEM.

Genera una clave nueva para cada operación lógica, y vuelve a enviar la misma clave solo al reintentar esa petición tras un tiempo de espera agotado o una conexión caída:

curl -X POST https://opfield.example.com/api/domains \
  -H "Authorization: Bearer $OPFIELD_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c6c1e-8a55-4c43-9d4e-2f1f8c3d9b10" \
  -d '{"domain":"app.example.com"}'

Una clave pertenece al token de API, al token OAuth o a la sesión del navegador que la envió, junto con los ámbitos efectivos actuales de quien llama, el método y la ruta exacta. Tras un cambio de ámbitos, la misma clave empieza de cero, de modo que una repetición nunca sobrevive a un acceso revocado.
Un reintento con la misma clave y la misma petición (la misma cadena de consulta y el mismo cuerpo JSON, en cualquier orden de claves) devuelve la respuesta guardada con la cabecera Idempotency-Replayed: true y no crea nada nuevo. Opfield conserva el resultado durante 24 horas, cifrado con su clave maestra, y escribe cada repetición en el registro de auditoría como api.idempotency.replay.
La misma clave con una petición distinta devuelve 422 IDEMPOTENCY_KEY_REUSED. La misma clave mientras la primera petición todavía se está ejecutando devuelve 409 IDEMPOTENCY_KEY_IN_PROGRESS con Retry-After. Una clave no válida devuelve 400 IDEMPOTENCY_KEY_INVALID.
Opfield nunca guarda una respuesta que parezca contener material secreto, como un token, una contraseña, una clave privada o credenciales, ni una de más de 1 MiB. Solo registra que la petición se completó, y un reintento devuelve 409 IDEMPOTENCY_RESPONSE_WITHHELD con el código original y Location cuando se conoce: busca el recurso en lugar de reintentar.
Solo se registran las respuestas 2xx y las respuestas 400, 404, 409 y 422 con un cuerpo JSON o vacío. Las respuestas 401, 403, 5xx, en streaming y de descarga no, así que un reintento después de ellas vuelve a ejecutar la petición.
No cubiertos: todos los endpoints fuera de la lista anterior, que se ejecutan con normalidad e ignoran la cabecera. Esto incluye a propósito los endpoints que devuelven un secreto una sola vez o reflejan una entrada sensible: tokens de API, de inferencia, de ingesta de logs y de despliegue de Pages, registro de nodos, claves de acceso y credenciales, vinculaciones, Access Lists y webhooks de notificación. Los cuerpos de petición de más de 1 MiB y las subidas que no son JSON también se ejecutan sin idempotencia, igual que todo mientras Redis, que guarda las claves, no está disponible.

Las herramientas de creación de MCP aceptan un argumento opcional idempotencyKey con las mismas reglas. La clave está ligada al token de MCP y a sus ámbitos, a los ámbitos actuales del propietario y a la herramienta. Solo se guardan los resultados correctos, de modo que un error de una herramienta se puede reintentar con la misma clave; un resultado repetido lleva _meta.idempotencyReplayed: true y se audita. Un resultado que parece contener un secreto no se guarda, y un reintento devuelve IDEMPOTENCY_RESULT_WITHHELD. El argumento se ofrece en:

Docker: create_docker_container, duplicate_docker_container y la operación de creación de manage_docker_deployment, manage_docker_compose, manage_docker_source, manage_docker_volume, manage_docker_network, manage_container_link y manage_docker_registry;
Tráfico entrante: create_route, create_route_folder y create_domain;
Certificados: request_acme_cert, la operación de subida de manage_ssl_certificate, create_root_ca y create_intermediate_ca;
Bases de datos y almacenamiento: la operación de creación de manage_database_connection, manage_managed_database, manage_storage_connection y manage_managed_storage;
Otros: la operación project_create de manage_pages, create_alert_rule y create_siem_destination.

Las herramientas que devuelven un secreto o reflejan una entrada sensible (create_node, create_access_list, create_webhook, la creación de vinculaciones, la creación de tokens y de claves de acceso, e issue_certificate) no aceptan el argumento. Las operaciones de ciclo de vida de Compose de manage_docker_compose conservan su propio argumento idempotencyKey con su significado anterior.

Mueve cargas grandes mediante enlaces de un solo uso

Las llamadas a herramientas son un mal canal para los archivos. Para las cargas grandes, las herramientas de MCP devuelven un enlace de un solo uso con un comando curl listo para usar que ejecuta una shell del lado del agente; los bytes pasan por Opfield, nunca por el modelo:

Pages: la operación link de upload_pages_artifact acepta un archivo comprimido, una carpeta de build empaquetada o un único archivo HTML. La subida puede ser tan grande como el File upload limit (100 MB por defecto, como máximo 500 MB); consulta la visión general de Pages. Sin shell, las operaciones de inicio, fragmento y finalización admiten como máximo 1 MiB por fragmento.
Archivos de contenedores: las operaciones link de download_docker_archive y upload_docker_container_archive exportan e importan archivos .gwca.
Objetos de almacenamiento: download_storage_object devuelve un enlace, válido durante 15 minutos, que descarga un objeto de cualquier tamaño, y upload_storage_object sube por fragmentos que Opfield verifica.

Un enlace funciona una vez, pertenece al token que lo pidió y se vuelve a comprobar contra los permisos actuales del propietario cuando se usa. Trátalo como una credencial de corta duración.

Gestión de errores

400 o 422: corrige la forma de la petición o los datos de validación;
401: actualiza o sustituye la autenticación;
403: distingue la falta de un ámbito de la falta de un derecho del plan;
404: verifica la visibilidad del recurso además de su existencia;
409: inspecciona el conflicto de ciclo de vida, la cuota o el estado actual;
429: aplica un backoff acotado y respeta las indicaciones del servidor;
5xx o nodo desconectado: conserva los ID de petición y comprueba el estado duradero del Task antes de reintentar.

Los errores de las herramientas de MCP y de AI Workspace empiezan con el mismo código que la respuesta de REST, por ejemplo NOT_FOUND, STORAGE_NOT_FOUND o NGINX_CONFIG_FAILED, seguido del mensaje y los detalles; un error de esquema dice VALIDATION_ERROR con los campos que fallan. Una petición a una ruta /api desconocida devuelve un 404 NOT_FOUND en JSON en lugar de la página de la consola.

Reglas de operación de MCP

Las herramientas de MCP cubren todas las operaciones sobre recursos y de gestión que permiten los ámbitos de la concesión OAuth, incluidos la configuración y los archivos de los nodos, las migraciones de Docker, el backend de logging, los ajustes de Opfield, los usuarios y los grupos, las operaciones de actualización y del Relay Pool, la administración de la inferencia, el hosting y los conectores de GitLab, GitHub, Git genérico, Cloudflare y SSH externo. MCP no expone las interioridades de AI Workspace, como las conversaciones, los planes y los sandboxes, ni herramientas que emitan tokens de API o autorizaciones OAuth. Consulta Qué pueden hacer y qué no los tokens.

Crear Routes y dominios no requiere permisos sobre nodos: create_route y create_domain pueden omitir el nodo cuando lo decide un dominio registrado o el único nodo Ingress compatible (para las Routes, ese nodo debe estar en línea), y list_route_ingress_nodes enumera los nodos en los que quien llama puede crear Routes. Consulta Elige el nodo Ingress.

El servidor MCP informa de la versión de Opfield como su versión. manage_opfield_diagnostics inspecciona el propio Opfield; consulta Diagnóstico de Opfield. Cuando una herramienta de MCP fija el entorno de un Deployment, lo combina con el entorno guardado, a diferencia de la ruta de despliegue de REST; consulta Publica una versión nueva.

Usa MCP para las operaciones orientadas a objetivos en las que el esquema de la herramienta añade seguridad y contexto del recurso. Lee las descripciones de las herramientas y las advertencias devueltas, pasa identificadores de recursos exactos y trata el contenido externo como una entrada no fiable. Las llamadas MCP se auditan y no deben usarse para eludir las comprobaciones de confirmación, permisos, derechos del plan o ciclo de vida.

Verificación

Para cada camino de automatización, prueba una acción permitida, una acción denegada, un fallo de validación, un éxito asíncrono y una operación interrumpida. Confirma la atribución en la auditoría y asegúrate de que los logs ocultan las credenciales y los campos sensibles de las peticiones.

Diseña clientes fiables

Modela la automatización como una conciliación y no como una secuencia de pulsaciones de botones a ciegas. Lee el recurso actual, compáralo con el estado deseado, envía el cambio mínimo necesario y verifica el estado resultante informado por el propietario. Usa ID estables en el estado guardado y nombres legibles solo para mostrarlos. Cuando una API expone un ID de operación o de Task, guárdalo junto con la ejecución de la automatización para que un operador pueda correlacionar un tiempo de espera agotado con el historial de Opfield.

Fija por separado plazos acotados para la conexión, la petición y la operación completa. Un plazo HTTP corto puede coexistir con un Task duradero de larga duración. Reintenta las lecturas y las actualizaciones explícitamente idempotentes con un backoff exponencial limitado y aleatorizado. No reintentes automáticamente creaciones, eliminaciones, migraciones, restauraciones ni rotaciones de credenciales tras un tiempo de espera ambiguo, salvo que la petición llevara una Idempotency-Key hacia un endpoint que la acepte o que la operación existente ya se haya conciliado.

Versiona el cliente frente al documento OpenAPI y las versiones de Opfield con las que realmente se ha probado. Rechaza los campos y los estados destructivos desconocidos en lugar de ignorarlos en silencio. Si una versión cambia un contrato de ciclo de vida, actualiza el cliente y sus pruebas de aceptación antes de desplegarlo en todas las instalaciones.

Despliegue y reversión seguros

Ejecuta la automatización nueva contra una carpeta o un conjunto de recursos desechables con ámbitos similares a los de producción. Registra la petición prevista, el Task resultante, el registro de auditoría y la verificación independiente del estado. Despliégala primero en una instalación o en un dominio de fallo y observa los errores y el retraso de la conciliación antes de ampliarla.

Revertir suele significar desactivar a quien hace la llamada, detener los envíos nuevos y aplicar una reversión compatible del producto a los recursos ya modificados. No significa eliminar Tasks ni editar el estado deseado en PostgreSQL. Conserva los ID de petición y los metadatos de las cargas fallidas, sin secretos, para que el responsable del producto pueda distinguir un defecto del cliente de un fallo de Opfield o de un daemon.