Use Spaw from Claude Code, Cursor, VS Code and Codex over MCP

Spaw speaks the Model Context Protocol, so an AI agent can verify email addresses, phone numbers, IPs, postal addresses and business identifiers, and compare them against each other, as tools instead of you pasting curl output into a chat — one at a time, or a whole list in one call. The server lives at https://spaw.co/mcp, uses streamable HTTP, and authenticates with the same secret API key as the REST API. Agent usage shows up on your Usage page as mcp · key name, so you can see what the agent spent. The sections below connect Claude Code, Cursor, Visual Studio Code and OpenAI's Codex; any other client that can send a request header connects the same way.

Connect Claude Code

1. Create a secret key on the API keys page. Use a dedicated key for the agent so you can revoke it without touching your servers, and export it as SPAW_KEY in the shell you run Claude Code from.
2. Register the server once:

claude mcp add --transport http spaw https://spaw.co/mcp \
  --header "Authorization: Bearer $SPAW_KEY"

The shell expands $SPAW_KEY when the command runs (in bash or zsh; in PowerShell write $env:SPAW_KEY, or use the single-quoted form that follows), so Claude Code stores the key itself; single-quote the header as 'Authorization: Bearer ${SPAW_KEY}' to store only the reference, which Claude Code reads from its environment each time it connects. The server is added to the current project only; add --scope user to use it in every project.

3. Ask for a verification in plain language, for example "check whether [email protected] can receive mail and tell me the reason if not". Claude Code calls the verify-email tool and reads the answer back.

Connect Cursor

Add to Cursor opens Cursor with the server filled in. Cursor fills in ${env:SPAW_KEY} from its own environment when it connects (some earlier releases sent it literally, so update Cursor if the server answers 401); export SPAW_KEY in your shell profile and restart Cursor after changing it. If nothing happens, Cursor may not be installed or the browser blocked the link; add the server by hand, in ~/.cursor/mcp.json for every project or .cursor/mcp.json for one:

{
  "mcpServers": {
    "spaw": {
      "url": "https://spaw.co/mcp",
      "headers": { "Authorization": "Bearer ${env:SPAW_KEY}" }
    }
  }
}

Connect VS Code

Install in VS Code opens Visual Studio Code with the server filled in. VS Code asks for the key the first time the server starts and keeps it in its secret storage, so nothing needs exporting. If nothing opens, VS Code may not be installed (VS Code Insiders takes vscode-insiders: links) or the browser blocked the link; add the server by hand, in your user mcp.json (run MCP: Open User Configuration from the Command Palette) or in .vscode/mcp.json for one workspace. VS Code's file lists servers under servers, not mcpServers, and the header takes the key from the input declared under inputs:

{
  "servers": {
    "spaw": {
      "type": "http",
      "url": "https://spaw.co/mcp",
      "headers": { "Authorization": "Bearer ${input:spaw-key}" }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "spaw-key",
      "description": "Spaw secret API key",
      "password": true
    }
  ]
}

Connect Codex

OpenAI's Codex adds the server with one command:

codex mcp add spaw --url https://spaw.co/mcp \
  --bearer-token-env-var SPAW_KEY

It writes this to ~/.codex/config.toml, which the Codex CLI, the Codex IDE extension and the ChatGPT desktop app share:

[mcp_servers.spaw]
url = "https://spaw.co/mcp"
bearer_token_env_var = "SPAW_KEY"

Codex stores the variable's name, not the key, and reads it each time it connects. If SPAW_KEY is unset or empty, Codex refuses to start the server and names the variable. A desktop app started from the Dock or the Start menu sees SPAW_KEY only if it is set in the environment the app launches with.

Other clients

Any other client that connects to remote MCP servers over streamable HTTP and can send a custom header works the same way: send Authorization: Bearer followed by your secret key to https://spaw.co/mcp, wherever that client keeps its configuration. ChatGPT on the web adds MCP servers as apps that sign in with OAuth or use no authentication; this server offers no OAuth, so it cannot be added there, while the ChatGPT desktop app reads the Codex configuration above. claude.ai's custom connectors expect OAuth too, except in Anthropic's request-headers beta for a limited set of organizations: choose No sign-in and add an Authorization request header whose value is Bearer followed by a secret key, which everyone in the organization then shares.

A missing or wrong key answers 401, and some clients, Cursor and VS Code among them, then try an OAuth sign-in and report an OAuth or registration error rather than a bad key, so check the key, or the variable that holds it, first. The full setup for each client is in the MCP server documentation.

The twelve tools

The fields and reasons are exactly the REST API's, so a reason of catch_all or an smtp_reason of greylisted means the same thing the reference pages describe. An agent that runs out of credits receives a clear tool error naming INSUFFICIENT_CREDITS, never a half answer — except part-way down a list, where the batch tools answer the rows they could pay for and report meta.stopped_reason (insufficient_credits, or key_spend_cap when the key's own daily cap is what stopped it), so nothing already billed is thrown away.

What to do with the verdict

The useful pattern is to let the agent do the reading. Ask it to verify a list of addresses from a file, keep the ones answered deliverable, set aside risky ones with their reasons for a human to look at, and drop the undeliverable ones. Because the batch tool honours your suppression list, addresses that already bounced come back free and marked, and the agent can skip them without a lookup. For a domain the agent has never seen, domain-intelligence is the cheaper first question: it costs one credit only when the domain accepts mail, and it tells the agent whether the domain is a burner or a catch-all before any address is checked.

Limits and safety

Requests share the API's rate limit of 5 per second per account. Use a secret key, never a publishable one: the agent runs on your behalf from a server, and publishable keys only work from a browser on an allowed domain. Keys are shown once at creation and stored hashed; rotate the agent's key from the API keys page if a configuration file leaks.

Everything a secret key was limited to at creation holds here too. A key scoped to a product family can only call that family's tools — an agent reaching for another one gets a tool error naming KEY_SCOPE_DENIED, which it can read, rather than a failed connection it can only report. The daily credit cap counts what the agent's tool calls bill and refuses further calls with KEY_SPEND_CAP_REACHED once it is spent, so an agent left running overnight cannot spend more than you decided. A key with an address allowlist is refused from anywhere else before a tool runs at all. Give the agent its own key with the narrowest scopes it needs and a cap you would not mind paying: it is the cheapest way to bound what an autonomous loop can do.

Cost

Identical to the REST API. A fresh deliverable or risky verdict costs one credit; unverified answers, invalid input, repeats within seven days and the spaw.test test addresses are free, undeliverable verdicts are free within a fair-use allowance, one credit covers five IP lookups, and the balance tool is always free. Every account gets 100 free credits a month.