Email Verification MCP Server

An MCP (Model Context Protocol) server that exposes a verify_email tool for AI agents and MCP clients to verify email addresses through a stxructured, type-safe interface.

1. Project Overview

This project implements an MCP server that wraps an email verification service (InboxValid) behind a clean tool interface. An AI agent or MCP client calls verify_email(address) and receives a structured response indicating whether the address is valid, invalid, risky, or encountered an error.

A mock InboxValid API is included so the entire system is self-contained and runnable without external dependencies.

Related MCP server: email-verify

2. Architecture

MCP Client / AI Agent
        │
        ▼
┌─────────────────────┐
│    MCP Server        │  ← Exposes verify_email tool via stdio
│    (src/server.ts)   │
└────────┬────────────┘
         │
         ▼
┌─────────────────────────┐
│   InboxValid Client      │  ← HTTP client with retry/backoff
│   (services/             │
│    inboxValidClient.ts)  │
└────────┬────────────────┘
         │  HTTP POST /verify
         ▼
┌─────────────────────────┐
│   Mock InboxValid API    │  ← Express.js server with deterministic rules
│   (mock-api/server.ts)   │
└─────────────────────────┘

Separation of concerns:

3. Tech Stack

4. Installation

git clone <repository-url>
cd email-verification-mcp
npm install
npm run build

5. Running Locally

Start the Mock API

# Development (with hot reload)
npm run dev:mock-api

# Production (after build)
npm run start:mock-api

The mock API starts on http://localhost:3001.

Start the MCP Server

In a separate terminal:

# Development
INBOXVALID_API_URL=http://localhost:3001 npm run dev:mcp

# Production (after build)
INBOXVALID_API_URL=http://localhost:3001 npm run start:mcp

The MCP server communicates over stdio (standard input/output), as required by the MCP protocol.

Environment Variables

Copy .env.example to .env and adjust as needed.

6. MCP Tool

verify_email

Description: Verify whether an email address is valid, invalid, or risky using the InboxValid verification service.

Input:

{
  "address": "user@example.com"
}

Output (success):

{
  "address": "user@gmail.com",
  "status": "valid",
  "reason": "Mailbox appears deliverable"
}

Output (error):

{
  "address": "user@example.com",
  "status": "error",
  "reason": "Email verification service temporarily unavailable"
}

Statuses:

7. Error Handling

Raw stack traces are never exposed through the MCP tool.

8. Retry Strategy

Transient failures (network errors, timeouts, HTTP 5xx) trigger automatic retries:

Attempt 1 → immediate
Attempt 2 → 500ms delay
Attempt 3 → 1000ms delay

• Maximum attempts: 3

• Backoff: Linear (500ms × attempt number)

• Non-retryable: 4xx client errors are returned immediately

• Request timeout: 5 seconds per attempt

9. Testing

Run the full test suite:

npm test

Run tests in watch mode during development:

npm run test:watch

Test Coverage

10. Docker

Build and Run

docker compose up --build

This starts two services:

The MCP server waits for the mock API health check before starting.

Stop

docker compose down

11. Demo

GUI — MCP Inspector

The easiest way to interact with the server is the MCP Inspector web UI.

INBOXVALID_API_URL=http://localhost:3001 npx -y @modelcontextprotocol/inspector npx tsx src/server.ts

Server Connected

Valid Email Result

Invalid Email Result

CLI — Pipe JSON-RPC via stdio

You can also test entirely from the command line by piping JSON-RPC messages into the MCP server:

Valid Email

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"verify_email","arguments":{"address":"user@gmail.com"}}}' | \
  INBOXVALID_API_URL=http://localhost:3001 npx tsx src/server.ts

Invalid Email

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"verify_email","arguments":{"address":"test@invalid-domain.test"}}}' | \
  INBOXVALID_API_URL=http://localhost:3001 npx tsx src/server.ts

Risky Email

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"verify_email","arguments":{"address":"temp@example.com"}}}' | \
  INBOXVALID_API_URL=http://localhost:3001 npx tsx src/server.ts

CLI — Direct curl (Mock API)

# Valid
curl -X POST http://localhost:3001/verify -H 'Content-Type: application/json' -d '{"email":"user@gmail.com"}'

# Invalid
curl -X POST http://localhost:3001/verify -H 'Content-Type: application/json' -d '{"email":"test@invalid-domain.test"}'

# Risky
curl -X POST http://localhost:3001/verify -H 'Content-Type: application/json' -d '{"email":"temp@example.com"}'

# Health check
curl http://localhost:3001/health

Simulate Failure & Retry

# Trigger 2 failures on the mock API
curl -X POST http://localhost:3001/admin/fail -H 'Content-Type: application/json' -d '{"count":2}'

# Then verify — the client retries and eventually succeeds
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"verify_email","arguments":{"address":"user@gmail.com"}}}' | \
  INBOXVALID_API_URL=http://localhost:3001 npx tsx src/server.ts

12. Design Decisions

Why separate the MCP server from the InboxValid client?

The MCP server handles protocol concerns (tool registration, input/output formatting). The InboxValid client handles HTTP communication, retry logic, and response validation. This separation:

• Makes each layer independently testable

• Allows swapping the mock API for a real InboxValid service with zero changes to the MCP layer

• Keeps the retry/backoff logic encapsulated and reusable

Why structured responses instead of throwing errors?

The VerificationResult type always has address, status, and reason fields, even for errors. This means:

• MCP clients always receive predictable JSON, never raw exceptions

• Error handling is explicit and type-safe

• The AI agent can reason about failures without parsing error messages

Why Zod for validation?

Zod provides runtime type checking that complements TypeScript's compile-time checking. The MCP SDK also integrates natively with Zod schemas for tool input validation.

Why a mock API instead of mocking fetch?

A real Express server running on a random port during tests exercises the full HTTP path, including serialization, headers, status codes, and network errors. This provides higher confidence than mocking fetch.

License

MIT