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:

# stdio (default) — for a local MCP host that spawns the server
WEBBULA_API_KEY=wb_your_key npx -y @webbula/mcp

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

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, then restart/reload the client — the tools appear automatically.

Claude Code (CLI) — one command:

claude mcp add webbula -e WEBBULA_API_KEY=wb_your_key -- npx -y @webbula/mcp

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

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

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"],
      "env": { "WEBBULA_API_KEY": "wb_your_key" }
    }
  }
}

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

8 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 | — | — |

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.

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