Skip to main content
Glama
InboxValid MCP Server

InboxValid MCP Server

by aayusharmaaa

InboxValid MCP Server

MCP server that exposes verify_email for email deliverability checks. Built for the Tvaram / InboxValid.ai internship assignment (Task 2, Option A).

The InboxValid API is mocked. The focus is a typed tool interface that agents can call reliably.

npm run demo

Quick start

npm install
cp .env.example .env   # optional
npm test
npm run demo
npm run build
npm start

Requires Node 18+.

Related MCP server: Email Verification MCP Server

Tool contract

Input

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

Output

{
  "email": "user@example.com",
  "status": "valid",
  "reason": "Mailbox exists and is deliverable"
}

status is valid, invalid, or risky.

Architecture

Overview

┌─────────────────────────────────────────────────────────────┐
│  MCP client (Cursor, Claude Desktop, demo script, etc.)     │
└─────────────────────────────┬───────────────────────────────┘
                              │ verify_email({ address })
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  server.ts — MCP adapter                                    │
│  • Zod input/output validation                              │
│  • delegates to VerificationService                           │
│  • maps ProviderError → MCP tool error                      │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  verification.ts — business logic                           │
│  • normalize → syntax check → disposable check              │
│  • provider call (with retry) → map result                  │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  client.ts — provider boundary                              │
│  • ProviderClient interface                                   │
│  • MockProviderClient (assignment)                          │
│  • InboxValidClient stub (production swap-in)               │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
                    Mock InboxValid API

types.ts — shared schemas, errors, config (used by all layers)

Request flow

address
  │
  ├─ normalize (trim, lowercase)
  │
  ├─ syntax invalid? ──────────────────► { status: "invalid" }
  │
  ├─ disposable domain? ───────────────► { status: "risky" }
  │
  ├─ provider.verify() with retry
  │     │
  │     ├─ deliverable: false ─────────► { status: "invalid" }
  │     ├─ risk_level: medium/high ────► { status: "risky" }
  │     └─ deliverable + low risk ─────► { status: "valid" }
  │
  └─ provider failure (after retries) ─► MCP tool error

Layers

File

Role

server.ts

MCP transport and tool registration. No verification rules.

verification.ts

Pipeline orchestration, local checks, retry, result mapping.

client.ts

External API abstraction. Mock today; real HTTP client later.

types.ts

Zod schemas, ProviderError, env config.

MCP is one adapter. The same VerificationService could back a REST endpoint without changing core logic.

Error boundaries

Layer

Handles

MCP (server.ts)

Bad tool input shape, unexpected handler failures

Service (verification.ts)

Syntax/disposable short-circuit, response mapping

Retry (withRetry)

Transient provider errors only

Client (client.ts)

HTTP transport, provider-specific failures

Email problems return a normal VerificationResult. API failures throw ProviderError.

Retry policy

Error

Retries

429, 5xx, timeout, network

Yes

400, malformed response

No

Backoff: baseDelayMs × 2^attempt. Default config allows 3 total attempts.

RETRY_MAX_ATTEMPTS=2
RETRY_BASE_DELAY_MS=100
DISPOSABLE_DOMAINS=mailinator.com,tempmail.com

Demo

npm run demo

Runs verify_email in-process for: valid email, bad syntax, disposable domain, and a transient failure that succeeds on retry.

Cursor MCP config

{
  "mcpServers": {
    "inboxvalid": {
      "command": "node",
      "args": ["dist/server.js"],
      "cwd": "/path/to/tvaram"
    }
  }
}

Dev mode (no build):

{
  "mcpServers": {
    "inboxvalid": {
      "command": "npx",
      "args": ["tsx", "src/server.ts"],
      "cwd": "/path/to/tvaram"
    }
  }
}

Mock provider scenarios

Force in tests:

new MockProviderClient({ scenario: "timeout" })

Or use the local part of the address: invalid@…, risky@…, timeout@…, ratelimit@…, servererror@….

Project layout

src/
  server.ts
  verification.ts
  client.ts
  types.ts
tests/
scripts/demo.ts

Assumptions

  • Mock backend is sufficient for the assignment brief.

  • Three statuses are enough for agent decision-making.

  • Disposable domains are checked locally before calling the provider.

  • stdio MCP transport is enough for local use and demos.

Production next steps

  • Implement InboxValidClient with real HTTP, auth, and timeouts.

  • Add logging and metrics on retry attempts.

  • Expand disposable-domain detection.

  • Short-TTL cache for repeat lookups.

Tests

npm test

65 tests covering types, validation, provider scenarios, retry behaviour, and MCP tool calls via in-memory transport.

Available Tools

1 tool
verify_emailA

Verify an email address and return a structured deliverability result.

Inputs: address (required). Returns: email, reason, status

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 1 tool

    Disambiguation5/5

    Only one tool exists, so there is no possibility of confusing it with another. Its purpose is entirely unambiguous.

    Naming Consistency5/5

    verify_email follows a clear verb_noun convention, which is consistent and predictable even with a single tool.

    Tool Count4/5

    A single tool for a narrowly scoped email verification service is reasonably appropriate, though it sits slightly below the typical 3-15 range.

    Completeness5/5

    The server's stated purpose is email verification with deliverability results, and verify_email fully covers this domain without leaving obvious missing operations.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables real-time email verification via MCP tools, checking syntax, MX, disposable domains, and optional SMTP probe to determine deliverability with a VALID/RISKY/INVALID verdict.
      2
      3 npm
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that provides email verification, returning valid, invalid, or risky status with detailed checks and metadata. It enables verifying email addresses via a simple tool interface.
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides email verification as an MCP tool, checking format, disposable domains, and mail server availability with structured results.
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides an MCP tool to verify email addresses, returning valid, invalid, risky, or error statuses via the InboxValid API. It includes a mock API and retry logic for robust, type-safe verification.
      MIT