Developers

Connect an AI agent with MCP

Set up ChatGPT, Claude, Hermes, Grok or Codex, check the connection, and control verification spending.

Choose your client

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

Connect with an API key or OAuth sign-in. Eligible ChatGPT, Claude and Grok connections can use OAuth; check your client’s account and role requirements below. Codex, Claude Code and Hermes also support direct API-key connections.

For API-key clients, create a labeled Test key in API keys as a workspace Owner or Manager. Save it in the client’s protected credentials or documented environment settings. Never put a key in a prompt, tool argument, URL or committed configuration.

The OAuth flow opens fairvalid.com for sign-in and consent. You choose an existing Live API key that covers the requested permissions, and review its workspace and lifetime cap. Approval grants the requested permissions together, within that key’s scopes. It does not ask you to paste that key into the AI client. Revoking the selected key also ends its connections. OAuth uses live keys; use a direct Test-key connection for the sandbox.

Client instructions reviewed on 23 October 2026. The hosted MCP protocol has passed production acceptance with the official SDK. That does not mean every named client has been tested; complete the connection check in your client before relying on it.

ChatGPT

Use the OAuth setup below. Current custom MCP connections require ChatGPT Business or Enterprise/Edu on the web, with permission to create plugins with MCPs. Business requires an admin or owner; Enterprise/Edu can authorize selected members.

Open Plugins, select the plus button, then Add custom MCP server. The current Plugins flow does not require Developer Mode.
Name the connection FairValid and enter https://mcp.fairvalid.com/mcp as the public HTTPS endpoint.
Choose OAuth with automatic client registration. FairValid uses public client registration: you do not need to supply a client ID or client secret. Never enter an API key in either field.
Complete the FairValid sign-in and consent described above. Review ChatGPT’s warning, then select Create as a plugin and inspect the six discovered tools.
Install the plugin, open a new conversation, type @ and select FairValid. Run the read-only connection check below before requesting a live verification.

Official documentation: OpenAI: connect a custom MCP server · OpenAI: OAuth authentication

Claude web and Desktop

Use a remote custom connector with OAuth. This is the same account-backed connection on Claude web and Desktop; it runs through Anthropic’s servers. On Team and Enterprise, an organization Owner adds the connector first. Enterprise members with a custom role that manages organization libraries can also add it.

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.

Open Customize → Connectors → Add custom connector. For a managed organization, an Owner or eligible Enterprise role starts in Organization settings → Connectors → Add → Custom → Web.
Enter FairValid and https://mcp.fairvalid.com/mcp.
Choose Sign in now. If an OAuth client choice appears, select Register automatically. Leave manually registered client ID and secret fields empty.
Sign in on fairvalid.com, review the selected live key and permissions, and approve the connection. Enable FairValid from the conversation’s connector controls.
Run the read-only connection check below. Use the sandbox check only if you connected with a Test API key through Request headers.

Official documentation: Anthropic: custom connectors and authentication · Anthropic: remote connector availability

Claude Code

Claude Code supports a direct API-key connection. Set FAIRVALID_API_KEY in the environment that launches Claude Code, using a Test key for the first check. Keep the actual secret out of project files.

Merge the configuration below into the project’s .mcp.json. Keep any existing servers. The literal environment reference belongs in the file; the key value does not.
Launch Claude Code with FAIRVALID_API_KEY available. Approve the project MCP configuration if requested.
Run claude mcp list, then inspect /mcp in the session. Confirm FairValid connects and exposes six tools, then perform the sandbox check below.

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

Official documentation: Anthropic: Claude Code MCP configuration

Hermes Agent

These instructions are for NousResearch Hermes Agent. Its remote HTTP transport supports bearer headers. The CLI stores the key in your active profile’s .env as MCP_FAIRVALID_API_KEY and keeps an environment reference in config.yaml.

Run the add command below. Answer yes when asked whether authentication is required, then enter a Test API key in the masked API key / Bearer token prompt.
Review the discovered tools and enable the FairValid tools you need. The setup must connect successfully; saving a disabled connection after an error is not a successful setup.
Run hermes mcp test fairvalid, then start a fresh session or run /reload-mcp. Perform the sandbox check below. Hermes may add its server-name prefix to the tool names.

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

hermes mcp test fairvalid

Official documentation: NousResearch: MCP configuration · NousResearch: MCP connection checks · NousResearch: header-auth CLI implementation

Grok Bot and Grok

Grok Bot and Grok.com have different setup surfaces. In a personal Grok Bot, ask the Bot to add FairValid using the request below. This route also works when the info pane only shows Details, Library and Computer, with no Setup section.

Team Bots additionally expose info pane → Setup → Plugins to the Bot’s owner or managers. That setup surface requires Team Bot access in the desktop app. Each teammate signs in with their own account when OAuth is used.

Grok.com uses grok.com/connectors → New Connector → Custom. Enter https://mcp.fairvalid.com/mcp and complete authentication. Business and Enterprise teams may need their administrator to provision the connector first. This is a separate connection from a Grok Bot plugin.

A bot built with the xAI API is also separate: its developer configures remote MCP headers in server code. These instructions do not claim that Grok Bot offers a generic Authorization-header field.

Ask your Bot to add the custom Remote HTTPS MCP connection using the request below. For a Team Bot, its owner or manager can also use Setup → Plugins.
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.
Complete FairValid consent on fairvalid.com. Each teammate connects their own account where required.
Ask the Bot to list FairValid’s tools and run the read-only connection check below. Tool discovery alone does not prove a verification completed.

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.

Official documentation: xAI: Grok Bot plugins and Remote HTTPS · xAI: Grok.com custom connectors · xAI: remote MCP for API developers

Codex

Use a direct API-key connection from Codex. Set FAIRVALID_API_KEY in the environment available to the Codex process, using a Test key for your first check. A desktop app launched independently may not inherit your terminal’s environment.

Run the command below to register the remote Streamable HTTP server. The command stores the environment variable’s name, not the API key.
Run codex mcp list and start a fresh Codex session so it loads the connection. Confirm FairValid appears in the session’s MCP tools.
If using the Codex app, make the variable available to its execution host and restart the app or open a fresh session as needed. Do not assume a successful CLI setup changed an already-running app’s environment.
Confirm six discovered tools and perform the sandbox check below.

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

codex mcp list

Official documentation: OpenAI: Codex MCP configuration

Check the connection before submitting work

Confirm discovery of all six tools listed below. A client may add its own prefix to tool names. Discovery confirms a connection, not successful verification.

With OAuth or a Live API key, grant balance permission and first ask the agent to call fairvalid_get_balance with no arguments. Reading the balance uses no verification credits. Do not submit the sandbox examples through a live connection.

With a Test API key, follow the sandbox check below instead. Live verification can reserve and spend credits; choose an address you are authorized to check and request the submission explicitly.

If a connection fails, check the account’s connector permissions, the endpoint, missing environment variables, and key or grant revocation. For permission or spending-cap errors, review the granted scopes or cap before retrying; a new idempotency key does not fix the cause.

Start with a free sandbox check

Use an fv_test_ key and call fairvalid_verify_email with the example below. The test-key single-address check returns a simulated result directly. It makes no provider call, creates no live verification and uses no credits.

Other reserved examples are undeliverable@example.com, risky@example.com, unknown@example.com, pending@example.com and error@example.com. Pending and error are deliberate simulations, not real mailbox checks. The single-address pending example has no job to poll.

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

Tools and permissions

fairvalid_verify_email takes email and idempotency_key. fairvalid_submit_job takes emails, idempotency_key and an optional name, for 1 to 5,000 addresses. Live submissions need submit scope.

fairvalid_get_job takes job_id to read state. fairvalid_get_results takes job_id and optional cursor, filter and search to read up to 50 results at a time. Live reads need read scope.

fairvalid_cancel_job takes job_id and requests cancellation; in-flight checks may finish. Live cancellation needs submit scope. fairvalid_get_balance takes no arguments and requires a live key with balance scope. Test keys cannot read a live credit balance.

Keys determine the workspace. Tools accept no API-key or workspace argument. Scope checks, revocation, spending caps and workspace credit rules apply to MCP just as they do to the customer API.

Follow a live job to its results

With OAuth or an fv_live_ key, both single and bulk verification submit asynchronous jobs. An accepted response and job_id mean the work was admitted, not that the mailbox check has finished. Processing time depends on the queue and verification provider.

For a sandbox rehearsal of the job flow, call fairvalid_submit_job with reserved example addresses. Sandbox jobs support state, results, cancellation and replay without provider calls or credit use.

Submit once with a stable idempotency_key and keep the returned job_id.
Call fairvalid_get_job with that job_id. Space polling requests out and back off during temporary failures.
Call fairvalid_get_results with the same job_id. Pass each next_cursor back as cursor until next_cursor is null. A cursor retains the original filter and search.
Check both the job state and each result. Unknown, catch-all and still-checking outcomes are not evidence that a mailbox is valid.

Retry without creating duplicate work

Both submission tools require an idempotency_key of 8 to 128 letters, digits, dots, colons, underscores or hyphens. Retry an uncertain response with the same API key or OAuth connection, idempotency_key and unchanged input. Replay is scoped to the underlying API key: rotating an OAuth access token keeps that identity, but selecting a different API key and resubmitting can create another run. A changed job payload with an existing idempotency key is rejected. Use a new idempotency key only for an intentional new run.

Check isError before reading the result. Calls that reach the customer API include its response and HTTP status in structuredContent; argument-validation errors can return only text content. Inspect an API error’s code and honor any retry hint. A timeout or temporary error does not prove the original submission was absent.

Live keys can spend workspace credits. Set a lifetime cap before connecting an autonomous agent: charged and reserved credits both count. Completed valid and invalid checks use one credit; unknown, unresolved catch-all and technical failures have no net verification charge.

Still need help?

Contact support