Conectar um agente de IA (MCP)

O próprio agente de IA de um escritório de imigração pode trabalhar no workspace dele no DS160.io por meio do MCP (Model Context Protocol). A partir dos documentos ou e-mails de um cliente, o agente pode criar um formulário, preencher as respostas que encontrar, verificar o que ainda falta e enviar ao cliente um link para completar o resto. Depois, a sua equipe confere o pedido e o assina no CEAC.

O agente se conecta a um único workspace empresarial e só pode fazer o que você permitir. Cada coisa que ele pode fazer é também um endpoint da API do DS160.io.

Antes de começar

• Um workspace empresarial. O MCP está disponível nos workspaces do tipo Business.
• Acesso de Proprietário ou Administrador. Apenas os Proprietários e Administradores de um workspace podem criar chaves de API ou autorizar uma conexão.
• Um cliente MCP. Claude Code, Cursor, VS Code, Codex e Windsurf se conectam com uma chave de API. claude.ai e ChatGPT se conectam entrando no DS160.io.

O endereço do servidor é:

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

Use este endereço mesmo que o seu workspace tenha um domínio próprio.

Conectar com uma chave de API

1. Abra Configurações do Workspace → Equipe e acesso → Chaves de API e clique em Criar chave de API.
2. Dê à chave o nome do agente (por exemplo Claude Code, equipe de admissão), escolha o preset MCP e crie a chave. O preset marca todos os scopes exceto runs:write; desmarque os que o agente não precisar.
3. Copie o segredo. Ele começa com ds160_sk_ e é mostrado uma única vez.
4. Adicione o servidor ao seu cliente com o segredo num cabeçalho Authorization. No Claude Code:

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

Os outros clientes usam o mesmo endereço e o mesmo cabeçalho nas suas configurações. No Cursor (.cursor/mcp.json):

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

No VS Code (.vscode/mcp.json), adicione os mesmos url e headers dentro de "servers" com "type": "http". Não deixe o segredo em arquivos que você faz commit: use as variáveis de ambiente ou as entradas secretas do seu cliente, quando houver.

Conectar o claude.ai ou o ChatGPT

O claude.ai e o ChatGPT não enviam uma chave. Em vez disso, eles se conectam entrando no DS160.io:

1. No claude.ai ou no ChatGPT, adicione https://www.ds160.io/api/mcp como conector personalizado.
2. Quando for pedido, entre no DS160.io com a sua própria conta.
3. Escolha o workspace empresarial em que o agente vai trabalhar.
4. Revise as permissões que ele pede e clique para autorizar.

A partir daí, o agente age como você, nesse workspace. Você precisa ser Proprietário ou Administrador do workspace para autorizar uma conexão.

Scopes: o que cada um permite

Scope	O que o agente pode fazer
forms:read	Listar formulários, ler o nome e o status de um formulário, verificar o que falta, acompanhar um envio
forms:write	Criar formulários (e lê-los)
forms:clone	Copiar um formulário existente para um novo
client-links:write	Criar links de cliente para enviar aos solicitantes
answers:read	Ler as respostas de um formulário
answers:write	Escrever e remover as respostas de um formulário
runs:write	Iniciar um envio no CEAC e acompanhá-lo

answers:read tira do DS160.io os dados pessoais dos solicitantes. Os nomes, datas de nascimento, números de passaporte, histórico de viagens e todas as outras respostas do DS-160 que o agente lê são passados ao agente e a quem o executa, como um provedor de IA. O seu workspace, como controlador dos dados dos seus clientes, decide se isso é permitido e é responsável por esses dados depois que saem do DS160.io (ver a política de privacidade e o Acordo de Tratamento de Dados). Se o agente só precisa preencher formulários, deixe answers:read de fora: só com answers:write, ele pode escrever respostas sem lê-las de volta.

O que o agente pode e não pode fazer

• Ele pode preparar um formulário: criá-lo, preencher respostas com o que o cliente enviou, ver quais perguntas ainda faltam ou seriam recusadas e enviar ao cliente um link para o resto.
• Cada resposta que ele escreve é verificada como o editor de formulários a verifica. O texto é guardado em maiúsculas, a menos que a pergunta aceite letras fora do inglês. Uma resposta que não se encaixa é recusada com um motivo, e o resto do lote não é afetado.
• Cada alteração fica registrada. O histórico de alterações do formulário mostra cada alteração como “API key nome” para uma chave, ou como “membro via agente” para uma conexão.
• Ele não pode assinar nem transmitir. Um envio iniciado por um agente sempre para antes de assinar, seja qual for a configuração do workspace: uma pessoa confere o pedido e o assina no CEAC (ver Revisar um DS-160 no CEAC antes de assinar).
• Ele não pode digitar os captchas do CEAC. Uma pessoa os digita no DS160.io enquanto o envio espera; o envio informa ao agente quando alguém é necessário e onde.
• Criar um formulário é cobrado como criá-lo no aplicativo: cada formulário criado, ou clonado, conta como um formulário criado.
• Ele só trabalha no próprio workspace. Não pode ver outros workspaces, e um formulário de outro workspace é informado como não encontrado.

Ferramentas

Ferramenta	O que faz	Scope
list_forms	Lista os formulários do workspace, do mais novo para o mais antigo	forms:read
get_form	Lê o nome, o status e o consentimento de um formulário	forms:read
create_form	Cria um formulário (cobrado por formulário criado)	forms:write
clone_form	Copia um formulário para um novo, com a opção de deixar seções de fora	forms:clone
create_client_link	Cria um link de cliente para um formulário	client-links:write
search_docs	Pesquisa nesta documentação, 200 pesquisas por dia por chave ou conexão	qualquer
describe_form_pages	Lista as páginas do formulário e cada pergunta: a rota da resposta, o tipo, se é obrigatória, os valores das listas suspensas e as perguntas que cada resposta abre, com o JSON de cada tipo de resposta	qualquer
get_answers	Lê as respostas de um formulário, do formulário inteiro ou de uma página	answers:read
set_answers	Escreve até 200 respostas por chamada, em ordem: cada uma é escrita, removida (valor null) ou recusada com um código e um motivo	answers:write
get_form_progress	Para cada seção: o status, as perguntas obrigatórias sem resposta e os problemas por rota; e se o formulário está completo	forms:read, answers:read ou answers:write
start_run	Inicia um envio no CEAC para o consulado escolhido; para antes de assinar	runs:write
get_run	O status de um envio, um resumo de onde ele está, se é necessária uma pessoa e o link para ele	runs:write ou forms:read

Revogar o acesso

• Uma chave: revogue-a em Configurações do Workspace → Equipe e acesso → Chaves de API. A próxima chamada do agente é recusada.
• Uma conexão (claude.ai, ChatGPT): revogue-a em Conta e Segurança, ou para todo o workspace em Configurações do Workspace. Ambos listam as conexões existentes.

Revogue imediatamente se uma chave puder ter vazado ou se um agente não for mais usado.

Limite o agente ao que o solicitante forneceu

Um DS-160 é assinado pelo solicitante, que declara que todas as respostas são verdadeiras. Diga ao seu agente para responder apenas com o que o solicitante lhe forneceu (os documentos, e-mails e respostas dele) e nunca adivinhar ou inventar uma resposta. Quando não tiver certeza, ele deve deixar a pergunta vazia, para que get_form_progress a mostre como em falta e o cliente ou a sua equipe a respondam. Revise o formulário antes que alguém o assine.

Solução de problemas

Problema	O que fazer
O cliente diz que não consegue se conectar, ou recebe 401	Confira se o endereço é https://www.ds160.io/api/mcp e se o cabeçalho é Authorization: Bearer <secret>, com o segredo completo. Uma chave revogada não pode ser usada de novo: crie uma nova.
Uma ferramenta diz que falta um scope	A chave ou a conexão não tem esse scope. Crie uma chave com ele (ou conecte de novo e autorize-o) e depois revogue a antiga.
Uma resposta é recusada	Leia o motivo. Use describe_form_pages para obter a rota correta e os valores que uma lista suspensa aceita.
start_run é recusado	get_form_progress lista o que falta ou está errado em cada seção. Preencha e inicie o envio de novo. Se já houver um envio do formulário em andamento, acompanhe-o com get_run.
O envio espera com needsPerson	Alguém abre o link do envio no DS160.io e digita o captcha. Quando o envio estiver pronto para assinar, alguém confere o pedido e o assina no CEAC.