InboxValid MCP Server

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

Manual Workflow

AI Workflow

MCP Tool

verify_email(address)

Input

{
  "address": "string"
}

Validated with Zod's email validator.

Output

{
  "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

   npm install
   

2. Run the demo client

   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

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:

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

Verify:

opencode mcp list

Codex

Register the local MCP server:

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

Verify:

codex mcp list

Claude Code

Register the local MCP server:

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

Verify:

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

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.