Plain-text copy for agents: /llms.txt (same content as /setup.txt). Endpoint: https://mailcheck.thinginn.com/mcp. You need an API key from the operator.
# Mailcheck MCP: setup and operating guide for an AI assistant
Updated: 9 November 2026.
## Task for the assistant reading this document
Configure Mailcheck in the user's MCP client, verify the connection, and make its email-verification tools ready to use. Default to Claude Code unless the user names another client. Inspect existing configuration first, preserve other servers, and reuse an existing correct Mailcheck entry. Do not claim setup is complete until a tool call succeeds. Reading this guide alone does not establish a connection: the client needs a valid key and an installed MCP configuration.
## Connection details
| Setting | Value |
|---|---|
| Server name | `mailcheck` |
| Remote MCP endpoint | `https://mailcheck.thinginn.com/mcp` |
| Transport | HTTP / Streamable HTTP; Claude Code configuration type `http` |
| Authentication | `Authorization: Bearer <API_KEY>` header |
| Suggested local environment variable | `MAILCHECK_API_KEY` |
| Public health check | `https://mailcheck.thinginn.com/api/health` |
The hostname contains **thinginn** with two n's. This is a hosted service: the client does not need to install the Rust server, open SMTP ports, set a sender address, or restart anything on the server.
## Credentials
The operator issues individual keys. The current user already has one. Use their existing key through the client's secure credential mechanism or local environment. Never request that they paste it into an AI conversation. Do not print it, include it in this guide, commit it to source control, or put it in a URL. There is no self-service key signup portal at present.
If the assistant cannot access a suitable secure input mechanism, let the user enter the key directly into their own terminal as described below. Stop only the credential-dependent step; do not invent a key or use an unrelated credential.
## Claude Code configuration
1. Check that Claude Code is installed with `claude --version`. Inspect existing MCP settings without exposing secret values. If Mailcheck is already configured at another scope, verify it before creating a duplicate.
2. In the intended project directory, merge the following entry into `.mcp.json`. Preserve existing `mcpServers` entries. The key reference is literal; do not replace it with a real key in the file.
```json
{
"mcpServers": {
"mailcheck": {
"type": "http",
"url": "https://mailcheck.thinginn.com/mcp",
"headers": {
"Authorization": "Bearer ${MAILCHECK_API_KEY}"
}
}
}
}
```
3. Ensure `MAILCHECK_API_KEY` is set in the environment that launches Claude Code. For manual entry on Linux/macOS, open Bash in that project directory and run the following yourself. The input is hidden and is not part of the command history. This sets the key for this shell session only.
```bash
read -r -s -p 'Mailcheck API key: ' MAILCHECK_API_KEY
printf '\n'
export MAILCHECK_API_KEY
claude
```
4. Approve the project MCP configuration if Claude Code requests it. Enter `/mcp` inside Claude Code and check Mailcheck's connection. An assistant that edited configuration from an existing session may need the user to start a new session with the environment variable available.
Claude Code's JSON configuration, environment references, and connection workflow are documented in the [official MCP guide](https://code.claude.com/docs/en/mcp). For another client, use its documented HTTP transport and custom Authorization-header support; do not assume it accepts Claude Code's JSON structure.
## Verify readiness
Use the MCP connection, not just the public health URL:
1. Discover tools and confirm `verify_email` and `verify_emails` are listed. The client may prefix their names with the server name.
2. Call `verify_email` with the exact arguments below.
3. Confirm `status` is `invalid` and `reason` is `malformed address`.
```json
{"email":"bad-address"}
```
This checks authentication, tool discovery, and execution without probing a real mailbox. The server's MCP tool result contains JSON encoded inside a text content block; parse that text to inspect the email result. An `isError: true` tool response is a tool failure, not an email-validity result.
Report readiness with the server URL, discovered tools, and actual test outcome. If no test was possible, say configuration is prepared but unverified. Do not display the key in the report.
## Tool reference
### `verify_email`
Checks one address. Required argument: `email`, a string.
Example input only:
```json
{"email":"person@example.com"}
```
### `verify_emails`
Checks a list. Required argument: `emails`, an array of strings. Maximum 200 addresses per MCP call. Split larger lists before calling; do not rely on the server to reject an oversized list, because the current implementation can truncate it.
Example input only:
```json
{"emails":["first@example.com","second@example.com"]}
```
Start with small batches, particularly for many addresses on one domain. Same-domain checks are serialized and can take time. Preserve the mapping to original input rows when saving results, including duplicates. Avoid overwriting the user's original file.
## Interpret results
Results include `email`, `status`, `reason`, `catch_all`, `mx`, `smtp_code`, `flags`, and `checked_at`. Preserve the supplied reason and flags; some fields can be null.
| Status | Interpretation |
|---|---|
| `valid` | Evidence suggests acceptance; delivery is not guaranteed. |
| `invalid` | The checker found a rejecting condition; inspect the reason. |
| `catch_all` | The domain accepts arbitrary recipients; this mailbox's existence is not established. |
| `unknown` | The check was inconclusive. Do not count it as invalid. |
The checker examines syntax, DNS/MX, SMTP responses, and catch-all behavior. It stops before sending an email message. A result does not establish inbox ownership, consent to contact, or permission to send outreach.
## Troubleshooting and current limitations
- HTTP 401: missing, incorrect, or revoked key; also check whether the client inherited `MAILCHECK_API_KEY`. Never log the header to diagnose it.
- HTTP 429: the hosted service's global concurrency limit was reached. Wait and retry with bounded backoff; reduce simultaneous calls.
- Timeouts: reduce batch size and inspect the client's timeout. Retry selectively instead of repeatedly rechecking an entire large list.
- Mailcheck missing from the client: inspect configuration scope, project approval, and whether a fresh session is needed.
- Health works but tools fail: health is unauthenticated and does not prove MCP access. Run the authenticated readiness check.
- Some mail providers block this server's IP. Outlook returned `unknown` with a Spamhaus-related rejection in a prior live check. Preserve that explanation; do not work around provider blocking or call it proof that a mailbox is invalid.
- Individual key issuance and revocation are available. Per-user usage quotas and a self-service signup portal are not implemented. Keys are activated or revoked by the operator's server restart workflow; clients do not perform that operation.
## Example user request after setup
“Use Mailcheck to check the email column in contacts.csv. Process bounded batches, keep the original file unchanged, and save the address, status, reason, flags, and checked_at value to contacts-checked.csv. Summarize all four statuses separately.”
## Provenance
Service details and tool schemas were checked against the deployed Mailcheck source. Public HTTPS authentication, two separate keys, tool discovery, malformed-address checking, and key revocation were tested on 9 November 2026. The user's `my-app` key also passed live authenticated tool discovery. These server checks do not mean the reader's own Claude Code session is already configured.