Email Verification MCP Server

A lightweight Model Context Protocol (MCP) server that exposes email verification as a structured tool that can be consumed by an MCP client or AI agent.

The server exposes a single tool:

verify_email(address)

The implementation performs email syntax validation, domain verification, and disposable-domain risk detection using a mock verification provider.

---

Overview

The goal of this implementation is to provide a clean interface through which another system or agent can request email verification and receive a structured result.

The implementation is intentionally modular:

MCP Client
    |
    | MCP / STDIO
    v
+----------------------+
|     MCP Server       |
|                      |
|    verify_email      |
+----------+-----------+
           |
           v
+----------------------+
| Verification Service |
|                      |
| - normalization      |
| - syntax check       |
| - domain check       |
| - risk check         |
+----------+-----------+
           |
           v
+-----------------------+
| Verification Provider |
|                       |
| Mock Provider         |
+-----------------------+

The MCP layer is kept thin, while the verification logic and provider dependency are separated from the transport layer.

---

Features

• MCP server using STDIO transport
• verify_email MCP tool
• Structured verification result
• Email normalization
• Email syntax validation
• Domain verification
• Disposable-domain detection
• Explicit provider error handling
• Mock provider for deterministic testing
• Unit tests
• MCP client integration test
• MCP Inspector demonstration

---

Tool Interface

verify_email

The MCP server exposes:

verify_email(address: string)

Input

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

Output

{
  "email": "user@example.com",
  "status": "valid",
  "reason": "Email syntax and domain checks passed.",
  "checks": {
    "syntax": true,
    "domain": true,
    "risk": false
  }
}

Possible statuses

Status	Meaning
valid	Syntax and domain checks passed
invalid	Email syntax or domain verification failed
risky	The domain is identified as disposable
error	The verification provider could not complete the check

The structured response allows an MCP client or agent to consume the verification result programmatically instead of parsing an unstructured text response.

---

Validation Flow

Input email
    |
    v
Normalize
(trim + lowercase)
    |
    v
Syntax validation
    |
    +------ invalid ------> invalid
    |
    v
Extract domain
    |
    v
Provider verification
    |
    +---- provider error ---> error
    |
    v
Domain exists?
    |
    +--------- no ---------> invalid
    |
    v
Disposable domain?
    |
    +--------- yes --------> risky
    |
    v
valid

1. Normalization

The input is stripped of surrounding whitespace and converted to lowercase.

For example:

  USER@EXAMPLE.COM

becomes:

user@example.com

2. Syntax Validation

The service first performs a lightweight syntax check.

Invalid syntax is rejected before making a provider call.

3. Domain Verification

After syntax validation, the domain is passed to the verification provider.

The mock provider simulates whether the domain exists.

4. Disposable-Domain Detection

The provider identifies domains included in the configured disposable-domain list.

A disposable domain produces:

status = risky

rather than invalid.

---

Architecture and Design Decisions

Thin MCP Layer

The MCP server is responsible for exposing the tool and passing the input to the verification service.

It does not contain the verification business rules.

This keeps the protocol layer simple and makes the core verification logic independently testable.

Verification Service

The verification service contains the application logic:

• normalization
• syntax validation
• provider invocation
• domain evaluation
• risk evaluation
• structured result creation

This separation means the service can be tested without requiring an MCP client.

Provider Separation

The verification service delegates domain verification to a provider.

The provider is currently implemented as a mock provider for deterministic testing.

Verification Service
        |
        v
MockEmailVerificationProvider

A real provider can later replace the mock without changing the MCP tool contract.

This keeps the external verification dependency replaceable and avoids coupling the MCP interface to a specific provider.

---

Error Handling

The implementation distinguishes between validation failures and provider failures.

Invalid Input

For malformed email syntax, the service returns an invalid result.

Invalid Domain

If the provider reports that the domain cannot be verified, the service returns an invalid result.

Disposable Domain

If the provider identifies the domain as disposable, the service returns a risky result.

Provider Failure

If the verification provider cannot complete the request, the service returns an error result.

This distinction is important because an invalid email and an unavailable verification service represent different conditions.

The implementation handles the expected ProviderError explicitly rather than broadly catching every exception and hiding unexpected programming errors.

---

Retry and Backoff

The current provider is a local mock and therefore does not require network retries.

For a production provider, retries would be appropriate only for transient failures such as:

• connection failures
• HTTP 429 responses
• temporary provider failures
• HTTP 5xx responses

Permanent validation failures should not be retried.

A production retry strategy could use bounded exponential backoff:

Request
   |
   v
Attempt 1
   |
   +---- success ---> result
   |
   +---- transient failure
              |
              v
           backoff
              |
              v
           Attempt 2
              |
              +---- transient failure
                         |
                         v
                      backoff
                         |
                         v
                      Attempt 3
                         |
                         +---- failure ---> error

The retry count and delays should be bounded to avoid increasing load on the provider during an outage.

---

Assumptions

The following assumptions were made for this implementation:

1. A real email verification API is not required for the implementation.
2. The external verification dependency is therefore represented by a mock provider.
3. Domain existence is simulated by the mock provider.
4. Disposable-domain detection uses a small predefined domain list.
5. SMTP mailbox verification is outside the scope of this implementation.
6. The MCP server is designed around STDIO transport for local MCP client integration.

These assumptions keep the implementation focused on the MCP integration and verification pipeline.

---

Testing

The project contains unit tests covering:

• valid email
• invalid email syntax
• disposable email
• email normalization
• invalid domain
• disposable domain
• provider failure

Run:

pytest

Current result:

7 passed

MCP Integration Test

The project also contains an MCP client integration test.

Run:

python tests/test_mcp_server.py

This verifies that:

1. The MCP server can be started.
2. An MCP session can be initialized.
3. The verify_email tool is discovered.
4. The tool can be invoked.
5. A structured verification result is returned.

---

MCP Inspector Demo

The implementation was tested using MCP Inspector.

1. Server Connection

The MCP server successfully connects using STDIO transport.

2. Tool Discovery

The MCP Inspector discovers the verify_email tool and exposes its required address input.

3. Tool Execution

The tool was invoked with:

user@example.com

and returned a structured verification result.

4. Automated Tests

The verification test suite passes all seven test cases.

---

Project Structure

email-verification-mcp/
│
├── src/
│   └── email_mcp/
│       ├── __init__.py
│       ├── models.py
│       ├── provider.py
│       ├── server.py
│       └── verifier.py
│
├── tests/
│   ├── test_verifier.py
│   └── test_mcp_server.py
│
├── screenshots/
│   ├── 01-server-connected.png
│   ├── 02-tool-discovery.png
│   ├── 03-tool-execution.png
│   └── 04-tests-passing.png
│
├── .gitignore
├── pyproject.toml
├── requirements.txt
├── uv.lock
└── README.md

---

Setup

Prerequisites

• Python 3.14+
• pip
• MCP Python SDK

1. Clone the Repository

git clone <repository-url>
cd email-verification-mcp

2. Create a Virtual Environment

On Windows:

python -m venv .venv
.venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Run Tests

pytest

5. Run the MCP Server

python -m email_mcp.server

The server uses STDIO transport and waits for an MCP-compatible client.

6. Run with MCP Inspector

mcp dev src/email_mcp/server.py --with .

---

Trade-offs

What I Optimized For

• Simplicity
• Modularity
• Testability
• Clear separation of concerns
• Minimal infrastructure
• Replaceable provider implementation

What I Intentionally Did Not Add

• Database
• Redis
• Message queue
• Web framework
• Real external verification API
• Complex deployment infrastructure

These components are not necessary to demonstrate the requested MCP interface and would add complexity to the current implementation.

The provider boundary leaves room to introduce production infrastructure when actual scale and reliability requirements justify it.

---

Scalability Considerations

The current implementation is intentionally small, but the architecture allows the verification pipeline to evolve without changing the MCP tool contract.

A production implementation could add:

• Real verification provider
• DNS/MX verification
• Provider timeouts
• Retry and backoff
• Rate limiting
• Domain-result caching
• Structured logging
• Metrics and monitoring
• Provider fallback
• Asynchronous processing for high-volume workloads

The important architectural decision is that these additions can be made behind the service/provider boundary rather than requiring a rewrite of the MCP interface.

---

Future Improvements

If this implementation were extended for production, I would prioritize:

1. Replace the mock provider with a real email verification API.
2. Add provider timeouts and bounded retries.
3. Add caching for repeated domain checks.
4. Add rate limiting.
5. Add structured logging and metrics.
6. Add integration tests for the real provider.
7. Benchmark concurrent verification requests.
8. Add provider fallback for improved availability.

---

Conclusion

The implementation provides a small, modular MCP server exposing email verification through a structured verify_email tool.

The main design goal was to keep the system:

• easy to understand
• independently testable
• modular
• lightweight
• replaceable at the provider layer

while leaving a clear path toward a production verification backend.