Skip to main content
Glama
satvikkesarwani

Email Verification MCP Server

by satvikkesarwani
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Email Verification MCP Server

A TypeScript MCP server that exposes a clean, well-typed verify_email tool for email verification.

The tool returns a structured result that an agent can consume:

  • valid

  • invalid

  • risky

  • reason

  • individual check results

  • metadata such as domain, provider, cache status, and lookup latency

It also includes a simple human-friendly CLI mode for demos, testing, and Loom recordings.

What This Project Does

This project implements Option A: MCP server.

It provides an MCP server over STDIO with the following tools:

Tool

Purpose

verify_email

Verifies an email address and returns valid, invalid, or risky with a reason

mcping

Confirms that the server is alive

mchelp

Shows help for available tools and topics

The main required tool is:

verify_email({
  email: "test@gmail.com"
})

Related MCP server: inboxvalid-mcp

Highlights

  • MCP-ready: Uses the official @modelcontextprotocol/server package.

  • Well-typed interface: Input and output schemas are defined with Zod.

  • Structured output: Returns machine-readable structuredContent for agents.

  • Readable output: Returns clear text output for humans.

  • Simple CLI demo mode: Run npm run verify -- test@gmail.com instead of writing raw JSON-RPC.

  • Validation pipeline: Syntax, domain, MX, and disposable-provider checks.

  • Mock backend support: Includes a deterministic backend layer suitable for local testing.

  • STDIO-safe logging: MCP mode keeps stdout clean for JSON-RPC transport.

Quick Start

cd /Users/satvikkesarwani/Desktop/tvaram
npm install
npm run build

Loom Demo Commands

Use these commands to quickly prove the system is ready.

1. Build the project

npm run build

2. Verify a valid email

npm run verify -- test@gmail.com

Expected style of output:

Email Verification Result
=========================

Email: test@gmail.com
Verdict: VALID - Safe to send
Reason: Email appears valid

Checks
------
Syntax: PASS
Domain exists: PASS
MX records: PASS
Disposable address: PASS - not disposable

Details
-------
Domain: gmail.com
Provider: not detected
Cached result: no
Lookup time: 1 ms

Recommendation
--------------
This address passed the available checks. It looks suitable for normal outreach.

3. Verify a risky disposable email

npm run verify -- test@guerrillamail.com

This should return a RISKY verdict because the domain is a known disposable email provider.

4. Verify an invalid email

npm run verify -- invalid-email

This should return an INVALID verdict because the email syntax is wrong.

5. Ping the server

npm run ping

This confirms the server package is responding.

CLI Usage

The project supports short CLI commands for human testing:

npm run verify -- test@gmail.com
npm run verify -- test@guerrillamail.com
npm run verify -- invalid-email
npm run ping
npm run help

You can also run the compiled file directly:

node build/index.js verify_email test@gmail.com
node build/index.js verify test@gmail.com
node build/index.js mcping
node build/index.js mchelp verify_email

Run without arguments to start the actual MCP server:

npm start

MCP Tool Interface

Tool Name

verify_email

Input Schema

{
  email: string;
  options?: {
    checkMx?: boolean;
    checkDisposable?: boolean;
    timeoutMs?: number;
  };
}

Output Schema

{
  email: string;
  status: "valid" | "invalid" | "risky";
  reason: string;
  checks: {
    syntax: boolean;
    domain: boolean;
    mx?: boolean;
    disposable?: boolean;
  };
  metadata: {
    domain: string;
    provider?: string;
    cached: boolean;
    latencyMs: number;
  };
}

Example Structured Result

{
  "email": "test@gmail.com",
  "status": "valid",
  "reason": "Email appears valid",
  "checks": {
    "syntax": true,
    "domain": true,
    "mx": true,
    "disposable": true
  },
  "metadata": {
    "domain": "gmail.com",
    "cached": false,
    "latencyMs": 1
  }
}

How MCP Clients Use It

The server uses STDIO transport. MCP clients should start it with:

node build/index.js

Example client configuration:

{
  "mcpServers": {
    "email-verifier": {
      "command": "node",
      "args": ["/Users/satvikkesarwani/Desktop/tvaram/build/index.js"]
    }
  }
}

The simple CLI commands are only for humans and demos. The MCP server mode remains available when the file is started without CLI arguments.

Available Scripts

Command

Description

npm run build

Compiles TypeScript into build/

npm start

Starts the MCP server over STDIO

npm run verify -- <email>

Runs human-friendly email verification

npm run ping

Runs a quick server status check

npm run help

Shows CLI help

npm test

Runs the test command

npm run lint

Runs the lint command

Verification Flow

1. Normalize the email address
2. Check the in-memory cache
3. Validate email syntax
4. Extract and validate the domain
5. Check MX records when enabled
6. Check disposable email providers when enabled
7. Fall back to the mock backend when needed
8. Return both readable text and structured content

Project Structure

tvaram/
├── src/
│   ├── config/
│   │   └── index.ts
│   ├── services/
│   │   ├── cache.ts
│   │   ├── mock-backend.ts
│   │   ├── retry.ts
│   │   └── verification.ts
│   ├── types/
│   │   ├── errors.ts
│   │   └── verification.ts
│   ├── utils/
│   │   ├── dns.ts
│   │   └── logger.ts
│   ├── validation/
│   │   ├── disposable.ts
│   │   ├── domain.ts
│   │   ├── pipeline.ts
│   │   └── syntax.ts
│   └── index.ts
├── build/
├── package.json
├── tsconfig.json
└── README.md

Configuration

Configuration lives in:

src/config/index.ts

Current defaults:

Area

Setting

Default

Server

name

email-verifier

Server

version

1.0.0

DNS

timeout

2000 ms

DNS

retries

1

Cache

max size

10000

Cache

TTL

1 hour

Retry

max attempts

3

Circuit breaker

threshold

5 failures

Circuit breaker

reset timeout

30 seconds

Mock backend

error rate

0.01

Design Notes

  • The MCP server writes protocol responses to stdout.

  • Logs are written to stderr so JSON-RPC messages are not corrupted.

  • CLI mode silences logs for clean human-readable output.

  • Zod schemas keep the tool input and output explicit and agent-friendly.

  • The verification backend is mockable so the MCP interface can be tested without depending on a paid or external verification API.

Limitations

  • This is not full SMTP mailbox verification.

  • DNS behavior can vary by network and resolver.

  • Disposable detection depends on the embedded blocklist.

  • The mock backend is deterministic and useful for testing, but it is not a production deliverability provider.

Submission Summary

This project satisfies the assignment requirement:

An MCP server exposing at least one tool, for example verify_email(address), returning a structured result: valid, invalid, or risky plus a reason.

The implementation includes:

  • MCP server over STDIO

  • verify_email tool

  • Zod input/output schemas

  • structured agent-readable result

  • readable human output

  • CLI demo commands

  • TypeScript build setup

Available Tools

3 tools
mchelpC

Show tool help and usage examples

ParametersJSON Schema
NameRequiredDescriptionDefault
topicNo

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description only states the basic function and does not disclose any side effects, permissions, or return behavior. Without annotations, the agent has no information about whether the tool is read-only or has other implications. This lack of transparency could lead to uncertainty.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no unnecessary words. It is well-structured and easy to read. It maintains high clarity in its brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is very minimal and lacks essential context about the tool's output, the meaning of the topic parameter, and any differentiation from siblings. Given the tool's simplicity, the description is insufficient for a fully informed invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description does not mention the 'topic' parameter at all. The schema provides an enum but no description, so the agent has no explanation of what each topic means or how to use them. This is a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: showing help and usage examples. It uses a specific verb and object, making the purpose unambiguous. However, it does not distinguish this tool from siblings, but that is a minor issue.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus the sibling tools. It does not mention any conditions or scenarios where this tool is preferred. This leaves the agent without explicit usage instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mcpingA

Check if the MCP server is alive and responsive

ParametersJSON Schema
NameRequiredDescriptionDefault
messageNo

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden. It indicates a non-destructive read-only operation ('check if alive and responsive') and does not imply any side effects. However, it does not specify what constitutes a response (e.g., return value or error), leaving some behavioral detail unspecified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that directly states the tool's function without redundancy or unnecessary detail. It is perfectly sized for a simple health-check tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, the description covers the core purpose but omits details about the parameter's role and the expected output or behavior on failure. For a basic ping-like tool, this might be acceptable, but the missing parameter explanation leaves a gap in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, 'message', is a string with no description in the schema or tool description. Its purpose is entirely unclear—whether it is an input to the check, an optional identifier, or something else. With 0% schema coverage and no explanatory text, the parameter's meaning is not conveyed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to check if the MCP server is alive and responsive. The verb 'check' is specific, and the resource is unambiguous. It is distinct from the sibling tools 'verify_email' and 'mchelp', which serve different functions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives. It implies a health-check use case, but there is no stated context, prerequisites, or comparison with sibling tools. The purpose is clear, but usage conditions are not elaborated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

verify_emailC

Verify an email address for deliverability and status

ParametersJSON Schema
NameRequiredDescriptionDefault
emailYes
optionsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
emailYes
checksYes
reasonYes
statusYes
metadataYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only says 'verify' without revealing that the tool likely performs network checks, uses timeouts, or has no side effects. No safety profile or operational behavior is disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single efficient sentence with no filler. The core action is front-loaded, and it earns its place, though it sacrifices detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even with an output schema present, the description omits meaningful context: there is no mention of optional settings, what checks are performed (MX, disposable), or whether the operation is read-only. An agent can call it with just 'email', but has no guidance on customizing behavior or interpreting the verification scope.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description mentions no parameters at all. It does not explain the 'email' field or the nested 'options' object with checkMx, timeoutMs, and checkDisposable. The agent must rely entirely on parameter names and defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Verify'), a clear resource ('an email address'), and the purpose ('deliverability and status'). It is immediately distinguishable from the unrelated sibling tools (mcping, mchelp).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus alternatives, nor any prerequisites or context. There is no explicit or implicit direction about choosing verify_email over another tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedmchelp
    • First observedmcping
    • First observedverify_email
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 3 tools

Disambiguation5/5

verify_email is the only domain-specific tool, while mcping and mchelp serve clearly separate utility purposes. There is no functional overlap or ambiguity between the tools.

Naming Consistency3/5

verify_email follows a clear verb_noun pattern, but mcping and mchelp use a different no-underscore 'mc' prefix style. The names are still readable, but the set does not follow a single consistent convention.

Tool Count4/5

Three tools is a reasonable count for a focused server, though two of the three are generic meta tools rather than domain operations. The effective domain surface is minimal but not unreasonable.

Completeness4/5

The core email verification operation is present and covers the primary need of checking deliverability and status. Batch verification or more granular diagnostics could be added, but agents can work around those gaps.

Resources

Related MCP Connectors

Related MCP Servers

  • inboxvalid-mcp

    vigneshachar283
    F
    license
    A
    quality
    B
    maintenance
    An MCP server that exposes a verify_email tool for checking email syntax, disposable domains, and MX records, returning a structured validity result.
    1
    -

  • InboxValid MCP Server

    siddreddy07
    F
    license
    Not graded
    quality
    C
    maintenance
    Provides email verification as an MCP tool, checking format, disposable domains, and mail server availability with structured results.
    -

  • inboxvalid-mcp

    KumarManglam-123
    F
    license
    A
    quality
    C
    maintenance
    An MCP server that exposes a mock email verification tool over stdio transport, providing structured JSON results with statuses valid, invalid, or risky.
    1
    -