Skip to main content
Glama
aayusharmaaa

InboxValid MCP Server

by aayusharmaaa
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
addressYesEmail address to verify

Output Schema

ParametersJSON Schema
NameRequiredDescription
emailYes
reasonYes
statusYes

TDQS

A3.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 the full burden of disclosing behavior. It states that a structured result is returned, but does not mention whether verification involves network calls, SMTP checks, sending a test email, or any side effects or limitations. This is a meaningful gap for a verification tool.

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, focused sentence that names the action and the outcome without any filler. It is front-loaded and easy to parse.

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

Completeness4/5

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

Given the simple single-parameter interface and the presence of an output schema, the description is nearly complete for invocation purposes. The main shortfall is the lack of behavioral context around how verification is performed, but this does not prevent an agent from calling the tool correctly.

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

Parameters3/5

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

The schema fully documents the only parameter, 'address', with a clear description. The tool description adds no additional nuance about formatting, normalization, or edge cases, but the schema coverage is 100%, so the baseline 3 is appropriate.

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 identifies the action (Verify) and the resource (an email address), and specifies that the output is a structured deliverability result. This is unambiguous and sufficiently distinguishes the tool for its intended use.

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

Usage Guidelines4/5

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

The description implies a clear use case: when an agent needs to validate an email address and obtain a deliverability verdict. There are no sibling tools or alternative options mentioned, so no exclusionary guidance is necessary. It lacks explicit 'when not to use' guidance but the context is reasonably clear.

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. Dates show when Glama detected each change.

  1. 1 tool updatev0.1.0
    • First observedverify_email
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
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.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • email-verify

    Baneado98
    A
    license
    A
    quality
    B
    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
    31
    MIT

  • Email Verification MCP Server

    satvikkesarwani
    F
    license
    Not graded
    quality
    C
    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.
    -

  • 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.
    -

  • Email Verification MCP Server

    05tanish
    F
    license
    Not graded
    quality
    C
    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.
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/aayusharmaaa/inboxvalid-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server