# MCP server for AI assistants

> Connect Claude, ChatGPT, Cursor, VS Code and other MCP clients to isBusinessEmail: server URL, OAuth sign-in, tools, example prompts and limits.

Source: https://isbusinessemail.com/docs/mcp

isBusinessEmail runs a remote **MCP server** ([Model Context Protocol](https://modelcontextprotocol.io)). Connect it once, and your AI assistant can check whether an address is a work email, classify a list of leads or find out whether a company runs Google Workspace or Microsoft 365, using your account and quota.

```text
https://api.isbusinessemail.com/mcp
```

| | |
|---|---|
| Transport | Streamable HTTP (JSON responses, no sessions) |
| Sign-in | OAuth 2.1 with PKCE, through your isBusinessEmail account. Or send an API key as a Bearer token. |
| Cost | Free. Each check counts toward your daily quota, like an API call. |

## Connect your assistant

### Claude (web, desktop and mobile)

1. Open **Settings → Connectors** and choose **Add custom connector**.
2. Name it `isBusinessEmail` and paste `https://api.isbusinessemail.com/mcp` as the URL.
3. Select **Connect**, sign in to isBusinessEmail (or create a free account) and select **Allow access**.

On Team and Enterprise plans, an owner adds the connector for the organization first.

### Claude Code

```bash
claude mcp add --transport http isbusinessemail https://api.isbusinessemail.com/mcp
```

Then run `/mcp` inside Claude Code and choose **Authenticate**. A browser window opens for sign-in.

### ChatGPT

Add a custom connector (in developer mode, depending on your plan) with the server URL `https://api.isbusinessemail.com/mcp` and OAuth authentication. ChatGPT registers itself and opens the sign-in page.

### Cursor

`~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "isbusinessemail": { "url": "https://api.isbusinessemail.com/mcp" }
  }
}
```

Cursor shows **Needs login** next to the server; select it to sign in.

### VS Code

`.vscode/mcp.json`:

```json
{
  "servers": {
    "isbusinessemail": { "type": "http", "url": "https://api.isbusinessemail.com/mcp" }
  }
}
```

### Any other client, with an API key

If your client can't do OAuth, use a secret key from [your dashboard](https://isbusinessemail.com/app/keys) as a header:

```json
{
  "mcpServers": {
    "isbusinessemail": {
      "url": "https://api.isbusinessemail.com/mcp",
      "headers": { "Authorization": "Bearer ibe_live_your_key" }
    }
  }
}
```

Keep keys out of shared repositories. An OAuth connection is safer: it creates its own key that you can revoke without touching your other integrations.

## Tools

| Tool | What it does | Counts as |
|---|---|---|
| `check_email` | Classifies one address: category, `is_business`, recommendation, reasons, typo suggestion, mail provider, Google Workspace / Microsoft 365 | 1 check |
| `check_domain` | The same for a domain, for when you only care about the company | 1 check |
| `check_batch` | Up to 100 addresses or domains in one call, results in input order | 1 check per item |
| `get_usage` | Tier, limits, checks used and remaining today, last 30 days | free |
| `report_wrong_verdict` | Reports a misclassified address or domain; a person reviews it | free (50 a day) |

The check tools take an optional `policy` (`b2b`, `strict` or `lenient`; see [Categories and policies](https://isbusinessemail.com/docs/categories-and-policies)). Every tool returns a short text summary for the assistant and the full API response as structured content, with the same fields as [`POST /v1/check`](https://isbusinessemail.com/docs/check-endpoint).

## Things to ask

- "Is jane@acme.io a work email? Does Acme use Google Workspace or Microsoft 365?"
- "Here are 40 sign-ups from this week. Which ones are personal or disposable?"
- "Score these leads by email domain and tell me which to send to sales."
- "Why was contoso.com classified as business? Show me the reasons."
- "How many checks do I have left today?"

## How sign-in works

The server follows the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization):

1. Without a token, `/mcp` answers `401` with a `WWW-Authenticate` header pointing at `https://api.isbusinessemail.com/.well-known/oauth-protected-resource/mcp`.
2. The client reads the authorization server's metadata at `https://api.isbusinessemail.com/.well-known/oauth-authorization-server`, then registers itself (dynamic client registration).
3. You sign in at isbusinessemail.com and approve the app. PKCE (S256) is required.
4. The app receives a secret key named **MCP · <app name>**. It shows up in [your keys](https://isbusinessemail.com/app/keys), with its own usage. Revoke it there to disconnect the app. Connecting the same app again replaces its previous key.

## Limits and privacy

- MCP checks use your account's [rate limits](https://isbusinessemail.com/docs/rate-limits) and daily quota. When the quota is used up, tools return a `quota_exceeded` error until 00:00 UTC.
- The MCP server sees the same data as the API: the addresses and domains your assistant sends. It never emails or probes them. See [Privacy and data](https://isbusinessemail.com/docs/privacy-and-data).
- Your assistant decides when to call a tool. Most clients ask before running tools; check your client's settings.

## Troubleshooting

| Symptom | Fix |
|---|---|
| The client says the server needs authentication | Connect again and finish the sign-in in the browser. |
| "This account already has the maximum number of active API keys" | Revoke an unused key at [/app/keys](https://isbusinessemail.com/app/keys), then connect again. |
| Tools return `quota_exceeded` | Wait for the reset at 00:00 UTC, or [ask for more](https://isbusinessemail.com/contact). |
| Tools return `invalid_token` | The key was revoked. Connect again. |