Webbula MCP Server

Expose Webbula's email-intelligence data to AI agents as Model Context Protocol tools — verify and clean email addresses, validate full lead records, run batch files, and check your credit balance. Each verification result carries a trust block (data provenance and activity history) from Webbula's 20+ year dataset.

The server is a thin wrapper over the Webbula API: it validates input, calls the API over HTTPS, and reshapes the response. It performs no scoring of its own — every verdict comes from Webbula.

Installation

You need Node.js 20+ and a Webbula API key. Run the published package directly with npx — no clone, no build. The examples pin @latest, so every launch resolves the newest published release (subject to the local npx cache).

🔑 Where the API key goes

The key is supplied once, as the WEBBULA_API_KEY environment variable on the server process. There is no config file and no login step — wherever you see WEBBULA_API_KEY below, that is the only place the key belongs.

1. **In every example below, replace the placeholder wb_your_key with your real key.

# stdio (default) — for a local MCP host that spawns the server
#                    ┌─ replace with your real key
WEBBULA_API_KEY=wb_your_key npx -y @webbula/mcp@latest

# HTTP transport on port 4000 — for a remote/shared deployment
WEBBULA_API_KEY=wb_your_key PORT=4000 npx -y @webbula/mcp@latest --http

Choosing a version

The package follows semantic versioning. The @<tag-or-version> suffix after @webbula/mcp selects which release npx resolves:

# latest — always the newest published release (recommended for most users)
WEBBULA_API_KEY=wb_your_key npx -y @webbula/mcp@latest

# pin an exact version — reproducible, never surprises you with an update
WEBBULA_API_KEY=wb_your_key npx -y @webbula/[email protected]

# a range — newest 1.x without crossing into a breaking 2.0
WEBBULA_API_KEY=wb_your_key npx -y @webbula/mcp@^1.7.0

• @latest resolves the newest published release on each launch (subject to the local npx cache). Convenient, but a new release can change behaviour between runs. To force a refresh past the cache, clear it with npx clear-npx-cache (or just re-run — npx revalidates periodically).
• @<exact-version> (e.g. @1.7.0) pins one release for fully reproducible launches — recommended for shared/CI deployments and for any config you check in.
• Call the version tool to confirm which release a running session is actually using; run npm view @webbula/mcp version for the latest published version and npm view @webbula/mcp versions to list everything published.

Wherever an example below uses @latest, you may substitute an exact version (e.g. @1.7.0) to pin it.

Connecting your AI tool

Every client launches the server over stdio and passes the key via env. Add a webbula entry to your client's MCP config — putting your real key in the WEBBULA_API_KEY slot shown in each example — then restart/reload the client so the tools appear automatically.

Claude Code (CLI) — one command:

#                                              ┌─ replace with your real key
claude mcp add webbula -e WEBBULA_API_KEY=wb_your_key -- npx -y @webbula/mcp@latest

Claude Desktop — edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "webbula": {
      "command": "npx",
      "args": ["-y", "@webbula/mcp@latest"],
      "env": { "WEBBULA_API_KEY": "wb_your_key" }
    }
  }
}

Put your real key in the WEBBULA_API_KEY value (the "wb_your_key" string).

Cursor — same mcpServers block as above, in ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project).

Windsurf — same mcpServers block, in ~/.codeium/windsurf/mcp_config.json.

VS Code (Copilot agent mode) — in .vscode/mcp.json; note the key is servers and each entry needs a type:

{
  "servers": {
    "webbula": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@webbula/mcp@latest"],
      "env": { "WEBBULA_API_KEY": "wb_your_key" }
    }
  }
}

Put your real key in the WEBBULA_API_KEY value (the "wb_your_key" string).

Configuration

The package is configured entirely through the environment — nothing else is required. The API key is held in memory for the duration of a request only; it is never logged, persisted, or returned in any tool output or error.

| Variable | Default | Purpose | |----------|---------|---------| | WEBBULA_API_KEY | — | Required. Your Webbula API key. Sent upstream as the X-API-KEY header. | | PORT | 3000 | Listen port for the HTTP transport. |

The same tool set runs under two transports (stdio or HTTP); the transport is chosen at launch (default stdio, --http for HTTP), everything else comes from the environment.

Authentication model. The key is configured once, on the server process, and every request uses it. The HTTP transport does not read a per-request Authorization / X-API-KEY header from inbound clients — run one server instance per key (per tenant, if you need multiple keys).

Tools

9 tools available. Every tool validates input with zod before any upstream call and returns the result both as pretty-printed text and as structuredContent.

| # | Tool | Category | Required params | Optional params | |---|------|----------|-----------------|-----------------| | 1 | verify_email | Email verification | email | profile | | 2 | hygiene_check | Email verification | emails (array, 1–100) | profile | | 3 | validate_lead | Lead validation | ≥1 of first_name, last_name, full_address, phone, emails | profile | | 4 | upload_file | Batch (async) | filename + content_base64 or data_source | profile, url, host, port, username, password, path, secure | | 5 | file_status | Batch (async) | package_name | — | | 6 | download_results | Batch (async) | package_name, filename | — | | 7 | get_credits | Account | — | — | | 8 | list_profiles | Account | — | — | | 9 | version | Server | — | — |

Capability breakdown

• Email verification & hygiene — verify_email returns a deliverability verdict, any corrected form, and a trust block for a single address; hygiene_check runs the same per-email classification + activity history over a list of 1–100.
• Lead validation — validate_lead parses and assesses a full contact record (name, postal address, phone) in one call, and runs email hygiene too when emails are supplied.
• Batch file processing (async) — upload_file submits a file (inline base64 or a web/FTP/SSH source) and returns a package_name; poll file_status, then pull each output with download_results (insert.csv / _report.xls).
• Account — get_credits reports the remaining balance per billing scenario with an explicit "unlimited" flag (consumes no verification credits); list_profiles lists the profile names the account may use. The profile-accepting tools (verify_email, hygiene_check, validate_lead, upload_file) run a preflight against this list and reject an unavailable profile — the one passed in the call or the server default — returning the available profiles instead of an opaque upstream rejection.
• Server — version reports the running @webbula/mcp release ({ name, version }) so an agent can confirm which build it is talking to — e.g. to check whether a fix or feature is present. It is local and read-only: no API key, no upstream call, and it consumes no credits.

Result vocabulary

Verification tools pass the upstream verdict token through verbatim as status (or per-email result) and attach a static, documented label / risk / usable for known tokens (unknown tokens keep the raw token, friendly fields omitted — the wrapper never guesses):

| Token | Label | Risk | Usable | |-------|-------|------|--------| | Clean / Valid | Clean / Valid | Low | ✅ true | | Unknown | Unknown | High to Moderate | — (indeterminate) | | Invalid | Invalid | Extreme | ❌ false | | Reputation | Reputation Threat | Extreme | ❌ false | | Fraud | Fraud Threat | Extreme to High | ❌ false | | Delivery | Delivery Threat | High | ❌ false | | Conversion | Conversion Threat | Moderate | ❌ false | | Beta | Beta Threat | Moderate to Low | ❌ false |

When upstream supplies activity data, a trust block is attached: { data_source, first_seen, last_seen, trajectory }.

Resources

This server exposes no MCP resources — all functionality is provided through the tools above.

License

MIT © Webbula, LLC