Conectar um agente de IA com MCP

Escolha seu cliente

Endpoint: https://mcp.fairvalid.com/mcp. Transporte: Streamable HTTP.

Conecte com uma chave de API ou login com OAuth. Conexões elegíveis do ChatGPT, Claude e Grok podem usar OAuth; confira abaixo os requisitos de conta e função do seu cliente. Codex, Claude Code e Hermes também aceitam conexões diretas com chave de API.

Para clientes com chave de API, crie uma chave de teste identificada em Chaves de API como Proprietário ou Gerente do espaço de trabalho. Salve-a nas credenciais protegidas do cliente ou nas configurações de ambiente documentadas. Nunca coloque uma chave em um prompt, argumento de ferramenta, URL ou configuração versionada.

O fluxo OAuth abre fairvalid.com para login e consentimento. Você escolhe uma chave de API Live existente que abranja as permissões solicitadas e revisa o workspace e o limite vitalício dela. A aprovação concede todas as permissões solicitadas de uma vez, dentro dos escopos dessa chave. Não é preciso colar essa chave no cliente de IA. Revogar a chave selecionada também encerra as conexões dela. O OAuth usa chaves Live; para o sandbox, use uma conexão direta com chave de teste.

Instruções dos clientes revisadas em 23 de outubro de 2026. O protocolo MCP hospedado foi aprovado nos testes de aceitação em produção com o SDK oficial. Isso não significa que todos os clientes citados foram testados; conclua a verificação de conexão no seu cliente antes de confiar nele.

ChatGPT

Use a configuração OAuth abaixo. As conexões MCP personalizadas atuais exigem o ChatGPT Business ou Enterprise/Edu na web, com permissão para criar plugins com MCPs. O Business exige um administrador ou proprietário; o Enterprise/Edu pode autorizar membros selecionados.

1. Abra Plugins, selecione o botão de adição e depois Adicionar servidor MCP personalizado. O fluxo atual de Plugins não exige o Modo de Desenvolvedor.
2. Dê à conexão o nome FairValid e informe https://mcp.fairvalid.com/mcp como endpoint HTTPS público.
3. Escolha OAuth com registro automático de cliente. O FairValid usa registro de cliente público: você não precisa informar um client ID nem um client secret. Nunca insira uma chave de API em nenhum desses campos.
4. Conclua o login e o consentimento do FairValid descritos acima. Leia o aviso do ChatGPT, selecione Create as a plugin e confira as seis ferramentas encontradas.
5. Instale o plugin, abra uma nova conversa, digite @ e selecione FairValid. Execute a verificação de conexão somente leitura abaixo antes de solicitar uma verificação real.

Documentação oficial: OpenAI: conectar um servidor MCP personalizado · OpenAI: autenticação OAuth

Claude web e Desktop

Use um conector personalizado remoto com OAuth. É a mesma conexão vinculada à conta no Claude web e no Desktop; ela passa pelos servidores da Anthropic. Nos planos Team e Enterprise, um Owner da organização adiciona o conector primeiro. Membros do Enterprise com uma função personalizada que gerencia as bibliotecas da organização também podem adicioná-lo.

Some organizations have a Request headers beta. For that alternative, choose No sign-in and add a required Authorization header with the full value Bearer <your FairValid API key>. If Request headers is absent, use OAuth or the Claude Code instructions below. The API key is not an OAuth client secret.

1. Abra Personalizar → Conectores → Adicionar conector personalizado. Em uma organização gerenciada, um Proprietário ou uma função Enterprise elegível começa em Configurações da organização → Conectores → Adicionar → Personalizado → Web.
2. Informe FairValid e https://mcp.fairvalid.com/mcp.
3. Escolha Sign in now. Se aparecer uma opção de cliente OAuth, selecione Register automatically. Deixe vazios os campos de client ID e secret de registro manual.
4. Entre em fairvalid.com, revise a chave Live selecionada e as permissões e aprove a conexão. Ative o FairValid nos controles de conectores da conversa.
5. Execute a verificação de conexão somente leitura abaixo. Use a verificação de sandbox apenas se você se conectou com uma Test API key por meio de Request headers.

Documentação oficial: Anthropic: conectores personalizados e autenticação · Anthropic: disponibilidade de conectores remotos

Claude Code

O Claude Code permite conexão direta por chave de API. Defina FAIRVALID_API_KEY no ambiente que inicia o Claude Code, usando uma chave de teste na primeira verificação. Mantenha o segredo real fora dos arquivos do projeto.

1. Mescle a configuração abaixo no arquivo .mcp.json do projeto. Mantenha os servidores existentes. A referência literal à variável de ambiente deve ficar no arquivo; o valor da chave, não.
2. Inicie o Claude Code com FAIRVALID_API_KEY disponível. Aprove a configuração MCP do projeto, se solicitado.
3. Execute claude mcp list e, em seguida, verifique /mcp na sessão. Confirme que a FairValid se conecta e expõe seis ferramentas e, depois, faça a verificação de sandbox abaixo.

{
  "mcpServers": {
    "fairvalid": {
      "type": "http",
      "url": "https://mcp.fairvalid.com/mcp",
      "headers": {
        "Authorization": "Bearer ${FAIRVALID_API_KEY}"
      }
    }
  }
}

Documentação oficial: Anthropic: configuração de MCP do Claude Code

Hermes Agent

Estas instruções são para o NousResearch Hermes Agent. O transporte HTTP remoto dele aceita cabeçalhos bearer. A CLI armazena a chave no .env do seu perfil ativo como MCP_FAIRVALID_API_KEY e mantém uma referência à variável de ambiente no config.yaml.

1. Execute o comando de adição abaixo. Responda sim quando for perguntado se a autenticação é necessária e, em seguida, insira uma Test API key no campo oculto API key / Bearer token.
2. Revise as ferramentas encontradas e ative as ferramentas da FairValid de que você precisa. A configuração precisa se conectar com sucesso; salvar uma conexão desativada após um erro não conta como configuração bem-sucedida.
3. Execute hermes mcp test fairvalid e, em seguida, inicie uma nova sessão ou execute /reload-mcp. Faça a verificação de sandbox abaixo. O Hermes pode adicionar o prefixo do nome do servidor aos nomes das ferramentas.

hermes mcp add fairvalid \
  --url https://mcp.fairvalid.com/mcp \
  --auth header

hermes mcp test fairvalid

Documentação oficial: NousResearch: configuração de MCP · NousResearch: verificações de conexão MCP · NousResearch: implementação de CLI com autenticação por cabeçalho

Grok Bot e Grok

O Grok Bot e o Grok.com têm áreas de configuração diferentes. Em um Grok Bot pessoal, peça ao Bot para adicionar a FairValid usando a solicitação abaixo. Esse caminho também funciona quando o painel de informações mostra apenas Details, Library e Computer, sem uma seção Setup.

Os Team Bots também exibem painel de informações → Setup → Plugins para o proprietário ou os gerentes do Bot. Essa área de configuração exige acesso de Team Bot no aplicativo para desktop. Cada colega entra com a própria conta quando o OAuth é usado.

O Grok.com usa grok.com/connectors → New Connector → Custom. Informe https://mcp.fairvalid.com/mcp e conclua a autenticação. Equipes Business e Enterprise podem precisar que o administrador provisione o conector primeiro. Esta é uma conexão separada de um plugin do Grok Bot.

Um bot criado com a API da xAI também é separado: o desenvolvedor configura os cabeçalhos de MCP remoto no código do servidor. Estas instruções não afirmam que o Grok Bot ofereça um campo genérico de cabeçalho Authorization.

1. Peça ao seu Bot para adicionar a conexão MCP HTTPS remota personalizada usando a solicitação abaixo. No caso de um Team Bot, o proprietário ou gerente também pode usar Setup → Plugins.
2. When the Bot shows the FairValid authorization card, select Authorize to open OAuth sign-in. Keep API keys out of the request and any server command.
3. Conclua o consentimento do FairValid em fairvalid.com. Cada colega conecta a própria conta, quando necessário.
4. Peça ao Bot para listar as ferramentas da FairValid e executar a verificação de conexão somente leitura abaixo. A descoberta de ferramentas, por si só, não comprova que uma verificação foi concluída.

Add FairValid as a custom Remote HTTPS MCP server at
https://mcp.fairvalid.com/mcp using OAuth.
Show me the sign-in flow, then list its tools.
Do not submit any email verification yet.

Documentação oficial: xAI: plugins do Grok Bot e HTTPS remoto · xAI: conectores personalizados do Grok.com · xAI: MCP remoto para desenvolvedores de API

Codex

Use uma conexão direta por chave de API a partir do Codex. Defina FAIRVALID_API_KEY no ambiente disponível para o processo do Codex, usando uma chave de teste na sua primeira verificação. Um aplicativo de desktop iniciado de forma independente pode não herdar o ambiente do seu terminal.

1. Execute o comando abaixo para registrar o servidor remoto Streamable HTTP. O comando armazena o nome da variável de ambiente, não a chave de API.
2. Execute codex mcp list e inicie uma nova sessão do Codex para que ela carregue a conexão. Confirme que a FairValid aparece nas ferramentas MCP da sessão.
3. Se estiver usando o app do Codex, disponibilize a variável no host de execução e reinicie o app ou abra uma nova sessão, conforme necessário. Não presuma que uma configuração bem-sucedida na CLI alterou o ambiente de um app que já estava em execução.
4. Confirme as seis ferramentas encontradas e faça a verificação no sandbox abaixo.

codex mcp add fairvalid \
  --url https://mcp.fairvalid.com/mcp \
  --bearer-token-env-var FAIRVALID_API_KEY

codex mcp list

Documentação oficial: OpenAI: configuração MCP do Codex

Verifique a conexão antes de enviar trabalhos

Confirme que todas as seis ferramentas listadas abaixo foram encontradas. Um cliente pode adicionar o próprio prefixo aos nomes das ferramentas. A descoberta confirma a conexão, não uma verificação bem-sucedida.

Com OAuth ou uma chave de API Live, conceda a permissão de saldo e peça primeiro ao agente que chame fairvalid_get_balance sem argumentos. Consultar o saldo não usa créditos de verificação. Não envie os exemplos do sandbox por uma conexão live.

Com uma chave de API Test, siga a verificação no sandbox abaixo. A verificação live pode reservar e gastar créditos; escolha um endereço que você esteja autorizado a verificar e solicite o envio explicitamente.

Se uma conexão falhar, verifique as permissões de conector da conta, o endpoint, variáveis de ambiente ausentes e se a chave ou a autorização foi revogada. Para erros de permissão ou de limite de gastos, revise os escopos concedidos ou o limite antes de tentar novamente; uma nova chave de idempotência não resolve a causa.

Comece com uma verificação grátis no sandbox

Use uma chave fv_test_ e chame fairvalid_verify_email com o exemplo abaixo. A verificação de endereço único com chave de teste retorna um resultado simulado diretamente. Ela não faz chamada a provedores, não cria verificação real e não usa créditos.

Os outros exemplos reservados são undeliverable@example.com, risky@example.com, unknown@example.com, pending@example.com e error@example.com. Pending e error são simulações intencionais, não verificações reais de caixa de correio. O exemplo pending de endereço único não tem job para consultar.

{
  "email": "deliverable@example.com",
  "idempotency_key": "agent-demo-2026-10-23"
}

Ferramentas e permissões

fairvalid_verify_email recebe email e idempotency_key. fairvalid_submit_job recebe emails, idempotency_key e um name opcional, para 1 a 5.000 endereços. Envios em produção exigem o escopo submit.

fairvalid_get_job recebe job_id para ler o estado. fairvalid_get_results recebe job_id e, opcionalmente, cursor, filter e search para ler até 50 resultados por vez. Leituras em produção exigem o escopo read.

fairvalid_cancel_job recebe job_id e solicita o cancelamento; verificações em andamento podem ser concluídas. O cancelamento em produção exige o escopo submit. fairvalid_get_balance não recebe argumentos e exige uma chave de produção com o escopo balance. Chaves de teste não podem ler um saldo de créditos de produção.

As chaves determinam o workspace. As ferramentas não aceitam argumentos de chave de API nem de workspace. Verificações de escopo, revogação, limites de gastos e regras de créditos do workspace se aplicam ao MCP da mesma forma que à API para clientes.

Acompanhe um job em andamento até os resultados

Com OAuth ou uma chave fv_live_, tanto a verificação individual quanto a em massa enviam jobs assíncronos. Uma resposta accepted e um job_id indicam que o trabalho foi admitido, não que a verificação da caixa de correio foi concluída. O tempo de processamento depende da fila e do provedor de verificação.

Para ensaiar o fluxo de jobs no sandbox, chame fairvalid_submit_job com endereços de exemplo reservados. Os jobs de sandbox oferecem estado, resultados, cancelamento e repetição sem chamadas a provedores nem uso de créditos.

1. Envie uma única vez com um idempotency_key estável e guarde o job_id retornado.
2. Chame fairvalid_get_job com esse job_id. Espace as solicitações de consulta e aumente o intervalo durante falhas temporárias.
3. Chame fairvalid_get_results com o mesmo job_id. Envie cada next_cursor de volta como cursor até que next_cursor seja null. Um cursor mantém o filtro e a pesquisa originais.
4. Verifique tanto o status do job quanto cada resultado. Resultados desconhecidos, catch-all e ainda em verificação não comprovam que uma caixa de correio é válida.

Tentar novamente sem criar trabalho duplicado

As duas ferramentas de envio exigem um idempotency_key de 8 a 128 caracteres, entre letras, dígitos, pontos, dois-pontos, sublinhados ou hifens. Repita uma resposta incerta com a mesma chave de API ou conexão OAuth, o mesmo idempotency_key e a entrada inalterada. A repetição é vinculada à chave de API subjacente: renovar um token de acesso OAuth mantém essa identidade, mas selecionar outra chave de API e reenviar pode criar outra execução. Um payload de tarefa alterado com uma chave de idempotência existente é rejeitado. Use uma nova chave de idempotência somente para uma nova execução intencional.

Verifique isError antes de ler o resultado. Chamadas que chegam à API do cliente incluem a resposta e o status HTTP em structuredContent; erros de validação de argumentos podem retornar apenas conteúdo de texto. Analise o code de um erro da API e respeite qualquer indicação de nova tentativa. Um tempo limite esgotado ou erro temporário não comprova que o envio original não ocorreu.

Chaves de produção podem gastar créditos do espaço de trabalho. Defina um limite vitalício antes de conectar um agente autônomo: créditos debitados e reservados contam. Verificações concluídas como válidas e inválidas usam um crédito; resultados desconhecidos, catch-all não resolvidos e falhas técnicas não consomem créditos ao final.