Conectar un agente de IA (MCP)

El propio agente de IA de un despacho de inmigración puede trabajar en su workspace de DS160.io mediante MCP (Model Context Protocol). A partir de los documentos o correos de un cliente, el agente puede crear un formulario, rellenar las respuestas que encuentre, comprobar lo que aún falta y enviar al cliente un enlace para completar el resto. Después, tu equipo revisa la solicitud y la firma en CEAC.

El agente se conecta a un único workspace empresarial y solo puede hacer lo que le permitas. Cada cosa que puede hacer es también un endpoint de la API de DS160.io.

Antes de empezar

Un workspace empresarial. MCP está disponible en los workspaces de tipo Business.
Acceso de Propietario o Administrador. Solo los Propietarios y Administradores de un workspace pueden crear claves de API o autorizar una conexión.
Un cliente MCP. Claude Code, Cursor, VS Code, Codex y Windsurf se conectan con una clave de API. claude.ai y ChatGPT se conectan iniciando sesión en DS160.io.

La dirección del servidor es:

https://www.ds160.io/api/mcp

Usa esta dirección aunque tu workspace tenga su propio dominio.

Conectar con una clave de API

Abre Configuración del Espacio de Trabajo → Equipo y acceso → Claves de API y haz clic en Crear clave de API.
Pon a la clave el nombre del agente (por ejemplo Claude Code, equipo de admisión), elige el preajuste MCP y crea la clave. El preajuste marca todos los scopes excepto runs:write; desmarca los que el agente no necesite.
Copia el secreto. Empieza por ds160_sk_ y se muestra una sola vez.
Añade el servidor a tu cliente con el secreto en un encabezado Authorization. En Claude Code:

claude mcp add --transport http ds160 https://www.ds160.io/api/mcp --header "Authorization: Bearer ds160_sk_…"

Los demás clientes usan la misma dirección y el mismo encabezado en su configuración. En Cursor (.cursor/mcp.json):

{
    "mcpServers": {
        "ds160": {
            "url": "https://www.ds160.io/api/mcp",
            "headers": { "Authorization": "Bearer ds160_sk_…" }
        }
    }
}

En VS Code (.vscode/mcp.json), añade los mismos url y headers dentro de "servers" con "type": "http". No dejes el secreto en archivos que subas al repositorio: usa las variables de entorno o las entradas secretas de tu cliente cuando las tenga.

Conectar claude.ai o ChatGPT

claude.ai y ChatGPT no envían una clave. En su lugar se conectan iniciando sesión en DS160.io:

En claude.ai o ChatGPT, añade https://www.ds160.io/api/mcp como conector personalizado.
Cuando te lo pida, inicia sesión en DS160.io con tu propia cuenta.
Elige el workspace empresarial en el que trabajará el agente.
Revisa los permisos que solicita y haz clic para autorizar.

A partir de ahí, el agente actúa en tu nombre en ese workspace. Debes ser Propietario o Administrador del workspace para autorizar una conexión.

Scopes: qué permite cada uno

Scope	Lo que puede hacer el agente
`forms:read`	Listar formularios, leer el nombre y el estado de un formulario, comprobar lo que falta, seguir un envío
`forms:write`	Crear formularios (y leerlos)
`forms:clone`	Copiar un formulario existente en uno nuevo
`client-links:write`	Crear enlaces de cliente para enviar a los solicitantes
`answers:read`	Leer las respuestas de un formulario
`answers:write`	Escribir y eliminar las respuestas de un formulario
`runs:write`	Iniciar un envío en CEAC y seguirlo

answers:read saca de DS160.io los datos personales de los solicitantes. Los nombres, fechas de nacimiento, números de pasaporte, historial de viajes y cualquier otra respuesta del DS-160 que lea el agente pasan al agente y a quien lo ejecute, como un proveedor de IA. Tu workspace, como responsable del tratamiento de los datos de sus clientes, decide si eso está permitido y es responsable de esos datos una vez que salen de DS160.io (ver la política de privacidad y el Acuerdo de tratamiento de datos). Si el agente solo necesita rellenar formularios, no le des answers:read: con answers:write solo, puede escribir respuestas sin volver a leerlas.

Lo que el agente puede y no puede hacer

Puede preparar un formulario: crearlo, rellenar respuestas con lo que envió el cliente, ver qué preguntas aún faltan o serían rechazadas, y enviar al cliente un enlace para el resto.
Cada respuesta que escribe se comprueba como la comprueba el editor de formularios. El texto se guarda en mayúsculas salvo que la pregunta admita letras que no sean del inglés. Una respuesta que no encaja se rechaza con un motivo, y el resto del lote no se ve afectado.
Cada cambio queda registrado. El historial de cambios del formulario muestra cada cambio como “API key nombre” para una clave, o como “miembro via agente” para una conexión.
No puede firmar ni enviar. Un envío iniciado por un agente siempre se detiene antes de firmar, sea cual sea la configuración del workspace: una persona revisa la solicitud y la firma en CEAC (ver Revisar un DS-160 en CEAC antes de firmar).
No puede escribir los captchas de CEAC. Los escribe una persona en DS160.io mientras el envío espera; el envío avisa al agente cuándo se necesita a alguien y dónde.
Crear un formulario se factura igual que crearlo en la aplicación: cada formulario creado, o clonado, cuenta como un formulario creado.
Solo trabaja en su propio workspace. No puede ver otros workspaces, y un formulario de otro workspace se indica como no encontrado.

Herramientas

Herramienta	Qué hace	Scope
`list_forms`	Lista los formularios del workspace, del más nuevo al más antiguo	`forms:read`
`get_form`	Lee el nombre, el estado y el consentimiento de un formulario	`forms:read`
`create_form`	Crea un formulario (se factura por formulario creado)	`forms:write`
`clone_form`	Copia un formulario en uno nuevo, con la opción de omitir secciones	`forms:clone`
`create_client_link`	Crea un enlace de cliente para un formulario	`client-links:write`
`search_docs`	Busca en esta documentación, 200 búsquedas al día por clave o conexión	cualquiera
`describe_form_pages`	Lista las páginas del formulario y cada pregunta: su ruta de respuesta, su tipo, si es obligatoria, los valores de los desplegables y las preguntas que abre cada respuesta, con el JSON de cada tipo de respuesta	cualquiera
`get_answers`	Lee las respuestas de un formulario, de todo el formulario o de una página	`answers:read`
`set_answers`	Escribe hasta 200 respuestas por llamada, en orden: cada una se escribe, se elimina (valor `null`) o se rechaza con un código y un motivo	`answers:write`
`get_form_progress`	Para cada sección: su estado, las preguntas obligatorias sin respuesta y los problemas por ruta; y si el formulario está completo	`forms:read`, `answers:read` o `answers:write`
`start_run`	Inicia un envío en CEAC para el consulado elegido; se detiene antes de firmar	`runs:write`
`get_run`	El estado de un envío, un resumen de dónde está, si se necesita a una persona y el enlace al envío	`runs:write` o `forms:read`

Revocar el acceso

Una clave: revócala en Configuración del Espacio de Trabajo → Equipo y acceso → Claves de API. La siguiente llamada del agente se rechaza.
Una conexión (claude.ai, ChatGPT): revócala en Cuenta y seguridad, o para todo el workspace en Configuración del Espacio de Trabajo. Ambos listan las conexiones que existen.

Revoca de inmediato si una clave puede haberse filtrado o si un agente ya no se usa.

Limita al agente a lo que dio el solicitante

Un DS-160 lo firma el solicitante, que declara que todas las respuestas son verdaderas. Indica a tu agente que responda solo con lo que el solicitante te dio (sus documentos, correos y respuestas) y que nunca adivine ni invente una respuesta. Cuando no esté seguro, debe dejar la pregunta vacía, para que get_form_progress la muestre como pendiente y la responda el cliente o tu equipo. Revisa el formulario antes de que nadie lo firme.

Solución de problemas

Problema	Qué hacer
El cliente dice que no puede conectarse, o recibe `401`	Comprueba que la dirección es `https://www.ds160.io/api/mcp` y que el encabezado es `Authorization: Bearer <secret>`, con el secreto completo. Una clave revocada no se puede volver a usar: crea una nueva.
Una herramienta indica que falta un scope	La clave o la conexión no tiene ese scope. Crea una clave con él (o vuelve a conectar y autorízalo) y luego revoca la anterior.
Se rechaza una respuesta	Lee el motivo. Usa `describe_form_pages` para obtener la ruta correcta y los valores que acepta un desplegable.
Se rechaza `start_run`	`get_form_progress` lista lo que falta o está mal en cada sección. Complétalo y vuelve a iniciar el envío. Si ya hay un envío del formulario en curso, síguelo con `get_run`.
El envío espera con `needsPerson`	Alguien abre el enlace del envío en DS160.io y escribe el captcha. Cuando el envío está listo para firmar, alguien revisa la solicitud y la firma en CEAC.