Waafir
Esta página é uma tradução automática pendente de revisão humana. Pode conter erros.

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/waafir

Complementos → 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/waafir

Em 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"
    }
  }
}

(Guia do Cursor)

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/waafir

Em 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 waafir

(Guia do Codex)

Conectar 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:

ServidorURL
waafir-redacthttps://app.waafir.io/api/mcp/waafir-redact
waafir-translatehttps://app.waafir.io/api/mcp/waafir-translate
waafir-dataroomhttps://app.waafir.io/api/mcp/waafir-dataroom
waafir-esignhttps://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-dataroom ou waafir-esign — na maioria das vezes um erro de digitação ou um /api/mcp sem 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. O waafir nunca responde 402: em vez disso, ele oculta as ferramentas pagas, e uma chamada a uma delas é recusada na camada 2 com QUOTA_EXCEEDED e uma mensagem que nomeia essa ferramenta e que também traz ADDON_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 Authorization está 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 403 CSRF 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-After nem 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ódigoSignificado
INVALID_ARGUMENTUm argumento está ausente, malformado ou não é um id válido — corrija-o e tente novamente
FORBIDDENO token é válido, mas não tem permissão para esta chamada
NOT_FOUNDO registro não existe ou não é seu
CONFLICTEntendido e permitido, mas a sala de dados não está em um estado em que a operação possa ser realizada
TOO_LARGEA entrada excede um limite de tamanho — divida-a
QUOTA_EXCEEDEDUma franquia medida foi esgotada; alguém precisa comprar ou fazer upgrade de algo
UPSTREAM_ERROR / UNAVAILABLEUma falha transitória em um serviço dependente — tente novamente mais tarde
INTERNALUma falha inesperada — não tente novamente, escale

Dois deles costumam pegar as pessoas de surpresa:

  • FORBIDDEN para um escopo baixo demais. Uma conexão ou token read não vê ferramentas de escrita, mas um cliente que chama uma delas mesmo assim é recusado pela ferramenta, então a recusa chega aqui como FORBIDDEN no payload — não como um HTTP 403. O mesmo vale para um token restrito a salas de dados específicas que informa como dataroom_id uma sala fora da sua lista de permissões. A maioria das ferramentas que recebem um id de arquivo ou pasta responde NOT_FOUND para 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. Um CONFLICT nã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 do waafir-dataroom lista 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.