# InboxValid MCP Server

A Model Context Protocol (MCP) server that exposes email verification as a tool for AI agents and MCP clients.

## Manual Workflow

| | |
| - | - |
| [![Manual workflow step 1](https://res.cloudinary.com/dtgf2auzt/image/upload/v1786535450/Screenshot_2026-08-12_171925_k0zeyo.png)](https://res.cloudinary.com/dtgf2auzt/image/upload/v1786535450/Screenshot_2026-08-12_171925_k0zeyo.png) | [![Manual workflow step 2](https://res.cloudinary.com/dtgf2auzt/image/upload/v1786535451/Screenshot_2026-08-12_172001_sgh7wb.png)](https://res.cloudinary.com/dtgf2auzt/image/upload/v1786535451/Screenshot_2026-08-12_172001_sgh7wb.png) |
| [![Manual workflow step 3](https://res.cloudinary.com/dtgf2auzt/image/upload/v1786535451/Screenshot_2026-08-12_172017_xottxt.png)](https://res.cloudinary.com/dtgf2auzt/image/upload/v1786535451/Screenshot_2026-08-12_172017_xottxt.png) | |

## AI Workflow

[![InboxValid MCP Server demo thumbnail](https://res.cloudinary.com/dtgf2auzt/image/upload/v1786534602/Screenshot_2026-08-12_170624_hpsbes.png)](https://res.cloudinary.com/dtgf2auzt/video/upload/v1786534506/Video_Project_8_hqhu9g.mp4)

## MCP Tool

`verify_email(address)`

### Input

```json
{
  "address": "string"
}
```

Validated with Zod's email validator.

### Output

```json
{
  "status": "valid | invalid | risky",
  "reason": "string"
}
```

The response includes both text content and `structuredContent`, allowing clients to consume the structured result directly.

## How to Run

1. **Install dependencies**

   ```bash
   npm install
   ```

2. **Run the demo client**

   ```bash
   npm start
   ```

   `client.js` spawns the MCP server (`src/server.js`), connects to it, and verifies a sample email (`john@gmail.com`). The result is printed to the console.

## Features

- Email format validation with Zod
- Disposable-domain detection
- Mocked MX-style mail-server check
- Retry with exponential backoff for transient failures
- Structured MCP tool output
- Distinguishes invalid from temporarily unverifiable emails

## Tech Stack

- Node.js
- JavaScript
- MCP SDK
- Zod

## Project Structure

```text
src/
├── server.js
├── client.js
└── validation/
    ├── verifyEmail.js
    ├── disposableDomains.js
    └── mx.js
```

## MCP Client Setup

Each client has its own way of registering an MCP server.

### OpenCode

Add the following to `opencode.json`:

```json
{
  "mcp": {
    "inboxvalid": {
      "type": "local",
      "command": ["node", "src/server.js"]
    }
  }
}
```

Verify:

```bash
opencode mcp list
```

### Codex

Register the local MCP server:

```bash
codex mcp add inboxvalid -- node src/server.js
```

Verify:

```bash
codex mcp list
```

### Claude Code

Register the local MCP server:

```bash
claude mcp add inboxvalid -- node src/server.js
```

Verify:

```bash
claude mcp list
```

## Compatibility

Tested with:

- OpenCode — verified

The server uses the standard MCP interface and communicates over stdio. Codex and Claude Code configuration is provided but not yet verified.

## Validation

- **Format**: Zod rejects invalid email syntax before verification runs.
- **Disposable domain**: checked against a predefined set. Returns `risky`; MX check is skipped.
- **MX-style check**: mocked mail-server check. Replaceable with DNS MX lookup or an external API without changing the MCP contract.

## Error Handling

- **Permanent results** (invalid format, disposable domain, no known mail server) are not retried.
- **Transient errors** (temporary service failure) are retried.
- If retries are exhausted, the email returns `risky`, not `invalid`, because the verification could not complete.

## Retry and Backoff

```text
Max attempts:   2
Max retries:     1
Base delay:      200ms
Backoff:         200ms → 400ms
```

Exponential backoff spaces out retries to avoid hammering a failing service. Only retryable failures trigger retries.

`service-error.com` is a mock domain used to simulate a transient service failure and test the retry mechanism.

## Error Strategy

| Condition                 | Result          | Retry |
| ------------------------- | --------------- | ----- |
| Invalid email format      | Rejected by Zod | No    |
| Disposable domain         | `risky`         | No    |
| No known mail server      | `invalid`       | No    |
| Temporary service failure | Retry           | Yes   |
| Retries exhausted         | `risky`         | No    |

## Testing

Covers: valid emails, invalid syntax, disposable domains, domains without mail servers, temporary failures, retry/backoff, exhausted retries, and structured MCP responses.

### Test Cases

| Email                      | Result    | Reason                                        |
| -------------------------- | --------- | --------------------------------------------- |
| `john@gmail.com`           | `valid`   | Passed basic verification checks              |
| `john@tempmail.com`        | `risky`   | Disposable email domain                       |
| `john@randomxyz123.com`    | `invalid` | Domain has no known mail server               |
| `john@service-error.com`   | `valid`   | Temporary service failure → retry succeeded   |
| `john@`                    | Rejected  | Invalid email format                          |
| `john`                     | Rejected  | Invalid email format                          |
| `@gmail.com`               | Rejected  | Invalid email format                          |

## Limitations

- Mocked verification backend
- No real DNS MX lookups, mailbox verification, production rate limiting, or persistent storage
- No real InboxValid API integration

## Trade-offs

- Simple architecture: each validation responsibility is a small, replaceable module.
- Structured output: predictable `{ status, reason }` contract for agents.
- Fail safely: unverifiable emails are `risky`, never falsely `invalid`.
- Replaceable verification layer: the mock is isolated from the MCP interface.