Bounceban

What Bounceban MCP server does

The Bounceban MCP server exposes BounceBan email verification to MCP-compatible clients. Its primary operation, bounceban_verify, checks one email address and returns the provider's verification information. The documented output includes a main status or result, an explicit catch-all indication, and flags for disposable, role-based, and free addresses.

The integration is intended for single-address checks rather than bulk processing. It is an independent, unofficial connection to BounceBan and is not published or endorsed by the provider. The package is also used as one verifier in Pipeworx's ordered email-enrichment workflow.

How it works

The Bounceban MCP server calls https://api-waterfall.bounceban.com/v1/verify/single. This host is selected for the waterfall workflow because it waits synchronously for a definitive response, with the provider documenting a possible server-side timeout after a long wait, rather than returning a task that the caller must poll.

Authentication uses the caller's BounceBan API key. Pass that value as _apiKey; the underlying request sends it in the Authorization header without a Bearer prefix. The package does not provide a shared platform key. Keys are obtained from BounceBan's API settings page.

Through Pipeworx, agents can connect to the pack endpoint or the full gateway. The pack endpoint includes the BounceBan operation together with shared Pipeworx meta-tools, while a local package exposes only this pack's tools. The gateway also supports routing questions through ask_pipeworx.

Setup and configuration

For a hosted connection, configure an MCP client with the pack URL:

{
  "mcpServers": {
    "bounceban": {
      "url": "https://gateway.pipeworx.io/bounceban/mcp"
    }
  }
}

For a local stdio connection, run the npm package with npx:

{
  "mcpServers": {
    "bounceban": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-bounceban"]
    }
  }
}

The local mode does not require a Pipeworx account or gateway round-trip. In either mode, provide a valid BounceBan key when calling the verification operation.

Tools and capabilities

• bounceban_verify(email, _apiKey): verifies one email address.
• Reports the provider's status or result.
• Identifies catch-all addresses.
• Exposes disposable, role, and free-address flags.
• Uses the waterfall-specific verification endpoint.

Limitations and notes

The exact successful response schema has not been confirmed with a live BounceBan key. In particular, the main verdict may be named status or result, and the complete set of possible status values is not established. Catch-all parsing accepts either is_catch_all or catch_all; if neither is present, it can infer catch-all status from the status text.

The Bounceban MCP server distinguishes missing or invalid authorization from a server-side verification timeout. A missing authorization header produces an authentication error, while an invalid key produces a separate invalid-authorization response. A documented HTTP 408 is surfaced as a verification timeout so callers can decide whether to retry or use another verifier. The gateway pack endpoint also lists shared meta-tools, so its tool count is larger than the BounceBan-specific operation list.