Configuração
Conectar um assistente de IA ao Waafir exige uma única URL: cole-a no seu assistente e faça login no Waafir quando ele pedir. Não há token para criar nem copiar. Esta página explica o login, o passo de adicionar servidor de cada assistente e como conectar com um token de acesso pessoal quando um assistente não consegue fazer login.
O básico
A URL. Uma única URL atende a todas as ferramentas do Waafir:
https://app.waafir.io/api/mcp/waafirComplementos → Configuração → Assistentes de IA mostra a URL da sua implantação, com um
botão de copiar. Substitua https://app.waafir.io se você estiver em uma implantação
diferente.
Login. Na primeira vez que seu assistente usa a URL, ele abre o Waafir no seu navegador. Faça login como de costume e revise a tela de consentimento:
- Em qual organização o assistente trabalha, se você pertence a mais de uma;
- Quais salas de dados ele pode acessar: todas ou apenas as que você escolher;
- O que ele pode fazer: leitura, escrita ou administração, nunca mais do que sua própria função permite, e se ele pode assinar documentos ou enviar para fora da sua organização;
- Confirme que é você. Se você configurou a autenticação de dois fatores, cada aprovação pede primeiro o seu código, assim como a criação de um token.
Aprove, e o navegador devolve você ao assistente. A conexão aparece em Complementos → Configuração → Assistentes de IA, onde você pode ver o que ela pode acessar e revogá-la. Veja Conexões.
Unverified app "…". Um assistente que se identifica por um endereço web
que controla é exibido por esse endereço, como claude.ai. Um que se registrou
por conta própria com um nome de sua escolha é exibido como Unverified app "<its name>":
o Waafir não consegue confirmar quem o criou, então só o aprove se você mesmo iniciou a
conexão.
O que a lista de ferramentas mostra. Os nomes das ferramentas começam com sua área: dataroom_,
esign_, redact_ e translate_. A lista mostra apenas as ferramentas que sua
conexão e sua organização podem usar: uma conexão somente leitura não vê
ferramentas de escrita, e as ferramentas de assinatura eletrônica aparecem apenas se sua organização tiver
o complemento E-Signatures ou uma assinatura ativa. Uma conexão também lista as
ferramentas que precisam de uma permissão que você não concedeu, como assinar ou enviar
para fora da sua organização. Se o assistente chamar uma delas, o Waafir recusa a chamada
e o assistente pede que você aprove novamente, desta vez com essa permissão
oferecida. Um token não pode pedir novamente, então sua lista omite essas ferramentas. Uma ferramenta
que não está listada continua sendo recusada com o motivo se um assistente a chamar
mesmo assim.
Conectar seu assistente
Cada seção abaixo traz o próprio passo de adicionar servidor do assistente e links para sua documentação (cada link verificado pela última vez em 23 de outubro de 2026). Nenhum destes assistentes foi testado ainda com o login do Waafir, por isso cada seção mantém a alternativa por token ao lado.
Claude (claude.ai e Claude Desktop)
Ainda não testado pelo Waafir. Abra Customize → Connectors, escolha Add → Add custom connector, dê um nome, cole a URL e continue. Deixe o login ativado e faça login no Waafir quando o Claude pedir. Para usá-lo em um chat, ative-o em + → Connectors. Em um plano Team ou Enterprise, um proprietário adiciona conectores em Organization settings → Connectors. (Guia do Claude)
Se o login não funcionar, adicione um cabeçalho de requisição Authorization: Bearer <token>
com um token (veja Conectar com um token em vez disso).
ChatGPT
Ainda não testado pelo Waafir. O ChatGPT acessa servidores MCP remotos em lugares diferentes dependendo do aplicativo; no aplicativo para desktop, abra Settings → MCP servers → Add server e cole a URL, depois faça login no Waafir quando solicitado. (Guia da OpenAI)
Se o ChatGPT não conseguir fazer login, use um token.
Claude Code
Ainda não testado pelo Waafir.
claude mcp add --transport http waafir https://app.waafir.io/api/mcp/waafirEm seguida, execute /mcp dentro do Claude Code (ou claude mcp login waafir no seu
shell) e faça login no Waafir no navegador. Adicione --scope user para usá-lo em
todos os projetos. Complementos → Configuração → Assistentes de IA tem esse comando pronto para
copiar.
(Guia do Claude Code)
Cursor
Ainda não testado pelo Waafir. Adicione a URL a .cursor/mcp.json (ou a
~/.cursor/mcp.json para todos os projetos) e faça login no Waafir quando o Cursor
pedir:
{
"mcpServers": {
"waafir": {
"url": "https://app.waafir.io/api/mcp/waafir"
}
}
}Se o Cursor não conseguir fazer login, adicione o cabeçalho de token mostrado em Conectar com um token em vez disso.
VS Code
Ainda não testado pelo Waafir. Execute MCP: Add Server na Command Palette,
escolha HTTP, cole a URL e dê a ela o id waafir. Faça login no Waafir
quando o VS Code pedir.
(Guia do VS Code)
Gemini CLI
Ainda não testado pelo Waafir.
gemini mcp add --transport http waafir https://app.waafir.io/api/mcp/waafirEm seguida, execute /mcp auth waafir e faça login no navegador. O login exige um navegador
local, por isso não funciona na maioria das sessões SSH remotas: use um token nesses casos.
(Guia do Gemini CLI)
Codex
Ainda não testado pelo Waafir.
codex mcp add waafir --url https://app.waafir.io/api/mcp/waafir
codex mcp login waafirConectar com um token em vez disso
Use um token de acesso pessoal
quando um assistente não consegue fazer login, ou para um script. Toda requisição leva o
token como bearer token no cabeçalho Authorization:
Authorization: Bearer waafir_pat_...Nunca faça commit de um token real em um arquivo ou repositório compartilhado; trate-o como uma senha. Complementos → Configuração → Tokens API tem um snippet pronto para copiar.
Servidores de área. Além do waafir, quatro servidores de área continuam disponíveis, para que uma
configuração existente continue funcionando. Cada um lista apenas as ferramentas da sua própria área,
filtradas da mesma forma, e mantém os nomes de ferramenta que sempre teve (list_files
em vez de dataroom_list_files). Você não precisa deles se conectar ao
waafir:
| Servidor | URL |
|---|---|
waafir-redact | https://app.waafir.io/api/mcp/waafir-redact |
waafir-translate | https://app.waafir.io/api/mcp/waafir-translate |
waafir-dataroom | https://app.waafir.io/api/mcp/waafir-dataroom |
waafir-esign | https://app.waafir.io/api/mcp/waafir-esign |
Não existe um endpoint /api/mcp sem sufixo: o segmento com o nome do servidor é obrigatório,
e uma requisição sem ele retorna 404. O waafir-esign é uma
oferta paga: sem o complemento E-Signatures
ou uma assinatura ativa, sua URL responde com um erro ADDON_NOT_PURCHASED.
No waafir, a mesma organização simplesmente não vê as ferramentas esign_.
Claude Code. Coloque primeiro o token em uma variável de ambiente, para que ele fique fora do histórico do seu shell:
export WAAFIR_PAT=... # the token you copied at issuance
claude mcp add --transport http waafir https://app.waafir.io/api/mcp/waafir \
--header "Authorization: Bearer $WAAFIR_PAT"Para compartilhar a configuração com um projeto, coloque a mesma entrada no .mcp.json dele.
O Claude Code expande ${WAAFIR_PAT} a partir do ambiente de cada pessoa, então o arquivo
pode receber commit sem o token dentro dele:
{
"mcpServers": {
"waafir": {
"type": "http",
"url": "https://app.waafir.io/api/mcp/waafir",
"headers": {
"Authorization": "Bearer ${WAAFIR_PAT}"
}
}
}
}O arquivo de configuração do Claude Desktop. O claude_desktop_config.json inicia servidores locais:
cada entrada é um command a executar, não uma url remota. Para acessar o Waafir
a partir desse arquivo, execute a ponte mcp-remote
(ela precisa de Node.js), que encaminha para o servidor remoto e adiciona seu
token como cabeçalho:
{
"mcpServers": {
"waafir": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://app.waafir.io/api/mcp/waafir",
"--header",
"Authorization:${WAAFIR_AUTH}"
],
"env": {
"WAAFIR_AUTH": "Bearer YOUR_WAAFIR_PAT"
}
}
}
}Mantenha o argumento Authorization:${WAAFIR_AUTH} sem espaços e depois reinicie
o Claude Desktop.
Cursor e outros clientes que aceitam uma URL e cabeçalhos.
{
"mcpServers": {
"waafir": {
"url": "https://app.waafir.io/api/mcp/waafir",
"headers": {
"Authorization": "Bearer YOUR_WAAFIR_PAT"
}
}
}
}Um servidor de área é adicionado da mesma forma, trocando a chave da entrada e a URL.
Chamar uma ferramenta
Depois de conectado, seu cliente lista as ferramentas do servidor (um tools/list do MCP)
e as chama em seu nome. Você não chama ferramentas manualmente — você pede ao cliente
de IA que faça algo ("liste os arquivos desta sala de dados", "traduza este
parágrafo para o francês") e ele seleciona e chama a ferramenta certa, passando os
argumentos documentados na referência de cada servidor. Veja as referências do
waafir-redact,
waafir-translate,
waafir-dataroom e
waafir-esign para os contratos
das ferramentas.
Quando algo dá errado
As falhas chegam em duas camadas diferentes, e elas não se parecem. Errar isso é o erro de integração mais comum aqui: um cliente que ramifica apenas pelo status HTTP vai ignorar silenciosamente todas as falhas do segundo tipo.
Camada 1 — a requisição foi recusada antes de qualquer ferramenta ser executada
Estes são status de erro HTTP reais, com um corpo de erro no formato JSON-RPC. Eles significam que a requisição nunca chegou a nenhuma ferramenta:
-
404 — Servidor MCP desconhecido. O segmento com o nome do servidor na URL não é um de
waafir,waafir-redact,waafir-translate,waafir-dataroomouwaafir-esign— na maioria das vezes um erro de digitação ou um/api/mcpsem nome de servidor. Corrija a URL. -
402 — Complemento não adquirido. O servidor é uma oferta paga (hoje:
waafir-esign) e sua organização não tem nem o complemento nem uma assinatura ativa. Um administrador da organização pode adquirir o complemento ou um plano nas configurações de cobrança. Uma organização sem direito não consegue sequer listar as ferramentas do servidor. Owaafirnunca responde 402: em vez disso, ele oculta as ferramentas pagas, e uma chamada a uma delas é recusada na camada 2 comQUOTA_EXCEEDEDe uma mensagem que nomeia essa ferramenta e que também trazADDON_NOT_PURCHASED. -
401 — Não autenticado. A credencial está ausente, malformada, revogada ou expirada. Para uma conexão, faça login novamente a partir do seu assistente: a maioria dos assistentes faz isso por você quando recebe o 401, e uma conexão que foi revogada, ou que ficou sem uso por 30 dias, precisa de um novo login. Para um token, verifique se o cabeçalho
Authorizationestá presente e se o token ainda está ativo em Complementos → Configuração → Tokens API; emita um novo se ele tiver sido revogado ou tiver expirado. Uma implantação anterior a esse comportamento responde a um token ausente ou malformado com 403CSRF validation failed: missing Origin; nesta superfície, isso também significa que o token está ausente ou malformado. -
403 — Proibido. A credencial foi rejeitada na entrada: foi usada uma sessão de navegador com login em vez de uma conexão ou de um PAT (sessões não são aceitas nesta superfície), ou sua organização impõe uma lista de IPs permitidos e a requisição veio de um endereço fora dela.
-
429 — Requisições demais. Você atingiu um limite de taxa do MCP. Nada aqui é vinculado ao seu endereço IP ou à sua organização — sua cota é a do seu token, então um colega na mesma organização e um segundo cliente na mesma rede não a consomem. O limite é de 60 requisições por minuto por token. Ele é contado antes de o token ser consultado, então um token malformado, revogado ou expirado também o consome, e as chamadas do mesmo token à API do Waafir fora do MCP contam para os mesmos 60. Os 60 de uma conexão com login também são contados por conexão, então o novo token que seu assistente recebe quando renova o login não reinicia a contagem de 60.
A resposta não traz cabeçalho
Retry-Afternem um código distintivo — todo 429 nesta superfície é igual — então recue seguindo um cronograma próprio em vez de repetir sem parar. Se um token não der folga suficiente, emita um segundo: o limite é por token.
Camada 2 — uma ferramenta foi executada e recusou
É aqui que vive a maioria das recusas, e isso não é um erro HTTP. A resposta
HTTP é 200 e o envelope JSON-RPC é um envelope de sucesso. A
falha vem dentro do resultado da ferramenta, que define isError: true e cujo
conteúdo de texto é:
{ "error": { "code": "CONFLICT", "message": "…" } }Ramifique por error.code. Os códigos são:
| Código | Significado |
|---|---|
INVALID_ARGUMENT | Um argumento está ausente, malformado ou não é um id válido — corrija-o e tente novamente |
FORBIDDEN | O token é válido, mas não tem permissão para esta chamada |
NOT_FOUND | O registro não existe ou não é seu |
CONFLICT | Entendido e permitido, mas a sala de dados não está em um estado em que a operação possa ser realizada |
TOO_LARGE | A entrada excede um limite de tamanho — divida-a |
QUOTA_EXCEEDED | Uma franquia medida foi esgotada; alguém precisa comprar ou fazer upgrade de algo |
UPSTREAM_ERROR / UNAVAILABLE | Uma falha transitória em um serviço dependente — tente novamente mais tarde |
INTERNAL | Uma falha inesperada — não tente novamente, escale |
Dois deles costumam pegar as pessoas de surpresa:
FORBIDDENpara um escopo baixo demais. Uma conexão ou tokenreadnão vê ferramentas de escrita, mas um cliente que chama uma delas mesmo assim é recusado pela ferramenta, então a recusa chega aqui comoFORBIDDENno payload — não como um HTTP 403. O mesmo vale para um token restrito a salas de dados específicas que informa comodataroom_iduma sala fora da sua lista de permissões. A maioria das ferramentas que recebem um id de arquivo ou pasta respondeNOT_FOUNDpara um item em tal sala, exatamente como para um id que não existe. Faça login novamente a partir do seu assistente e conceda o escopo ou as salas de dados corretos, ou emita um token com o escopo correto.CONFLICT. A chamada foi entendida e permitida, mas a sala de dados não está em um estado em que ela possa ser realizada — um nome de pasta já em uso, um arquivo cujo nome foi assumido desde então por um arquivo ativo, ou uma restauração cujo contêiner ainda está excluído ou cujo upload nunca foi concluído. UmCONFLICTnão é um problema de autorização, e fazer login novamente ou emitir o token de novo não vai ajudar; a mensagem nomeia o registro que bloqueia a operação, quando há um, para que você possa agir sobre ele e tentar novamente. A referência dowaafir-dataroomlista os conflitos que cada ferramenta pode retornar.
Um arquivo que ainda está sendo verificado. O Waafir verifica cada arquivo
recém-enviado e cada nova versão antes de servir o conteúdo. Até lá, uma
ferramenta que lê o conteúdo do arquivo responde UNAVAILABLE com
error.reason: "ACTIVATION_PENDING" e a mensagem
This file is still being checked. Try again shortly. É transitório: chame de
novo após uma breve espera.
Uma recusa clara em qualquer uma das camadas é o resultado esperado e seguro de uma chamada que o Waafir não vai atender — ele recusa a requisição em vez de fazer silenciosamente menos do que você pediu.