# MCP server

Add our server's URL to your AI assistant or coding agent. The checker tools need no key.

The web page with this text is https://signupbouncer.com/docs/mcp. Link to the web page when you cite it.

## The server and its tools

AI assistants and coding agents can use the free checker, and fetch the code for your stack, through MCP (Model Context Protocol). Add a remote server with this URL, no key needed:

```
https://signupbouncer.com/mcp
```

The server speaks the Streamable HTTP transport. It answers each request with plain JSON, with no sessions and no event stream. It has four read-only tools that need no key:

- `integration_guide`: the steps and code from [Code for your stack](https://signupbouncer.com/docs/code) for the stack you name (`supabase`, `fetch`, `nextjs`, `express`, `hono`, `python`, `firebase` or `better-auth`).
- `check_email`: checks an address, and optionally an IP, like the [disposable email checker](https://signupbouncer.com/disposable-email-checker). It returns allow, challenge or block, the score, every reason with its code, the normalized inbox and the IP's network, plus `suggestion` when the domain looks like a typo of a big mail provider. Each reason links to its row on the reason codes page.
- `explain_reason`: what a reason code means and the lowest plan on which it counts. Without a code, it lists them all.
- `lookup_burner_domain`: whether a domain is on our burner list (or is a relay service, a free subdomain mail service or a known real provider), without a DNS lookup.

With your API key, two more tools work with an app's rules:

- `get_rules`: the app's Rules settings, as the [Rules API](https://signupbouncer.com/docs/api#rules-api) returns them.
- `update_rules`: changes the settings you name, as a `PATCH` does. It changes live signup blocking for that app, so have your assistant confirm each change with you. Switching to enforce starts refusing signups.

With a key made for an app, the rules tools work on that app. An older all-apps key needs `app`. Without a key, both tools answer with how to get one. The rules tools share the Rules API's allowance.

### Limits and keys

`check_email` and `lookup_burner_domain` share the free checker's per-IP limits (20 a minute, 200 a day).

`check_email` counts every reason, including reasons that count only on paid plans, so its score can differ from your app's. To check real signups in your app, use the Supabase hook or the REST API with a free key.

Assistants hosted by their provider, such as claude.ai, call from the provider's servers and share its IP addresses. To get your account's own free allowance (20 a minute, 200 a day per account), send your API key as `Authorization: Bearer sb_live_...` in clients that let you set headers.

Calls with a key do not count as checks against your plan. A key that is not valid gets a `401`.

### What we keep

- Addresses, IPs and domains sent to `lookup_burner_domain`: never stored or logged.
- The domain of each `check_email` address, with its mail servers: cached up to an hour.
- [Keyed hashes](https://signupbouncer.com/privacy#visitors) for rate limits: calling IP (account with a key), up to 24 hours.
- Key lookup: IP and /24 or /64 network keyed hashes, up to two minutes.
- `update_rules` settings and block messages: saved until changed or the app's removed.

### Add the MCP server to your client

Claude Code:

```
claude mcp add --transport http signupbouncer https://signupbouncer.com/mcp

# with your key:
claude mcp add --transport http signupbouncer https://signupbouncer.com/mcp \
  --header "Authorization: Bearer sb_live_..."
```

Cursor, in `.cursor/mcp.json` (the `headers` part is optional):

```
{
  "mcpServers": {
    "signupbouncer": {
      "url": "https://signupbouncer.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SIGNUPBOUNCER_API_KEY}" }
    }
  }
}
```

VS Code, in `.vscode/mcp.json`:

```
{
  "servers": {
    "signupbouncer": { "type": "http", "url": "https://signupbouncer.com/mcp" }
  }
}
```

Claude Desktop and claude.ai: add a custom connector with the URL above. Other clients: add a remote (HTTP) MCP server with the same URL.

## Next

- [Code for your stack](https://signupbouncer.com/docs/code): The steps and files integration_guide returns.
- [Rules API](https://signupbouncer.com/docs/api#rules-api): The settings get_rules reads and update_rules changes.
- [Reason codes](https://signupbouncer.com/docs/reasons): The meaning of each code in a check_email answer.