inboxvalid-mcp

An MCP server exposing a verify_email tool, built for the InboxValid.ai internship assignment (Task 2, Option A).

What it does

Exposes one MCP tool, verify_email(address), that runs three checks in order and returns a structured result:

1. Syntax — pragmatic email-shape validation (not full RFC 5322, which is mostly academic in practice).
2. Disposable domain — checks the domain against a small mocked known-bad list.
3. MX record — a real DNS MX lookup confirming mail-routing plausibility (not mocked).

Checks run in this order because syntax and disposable-domain checks are local and free, while MX is the only network-bound step — so a malformed address never triggers a DNS call at all.

Tool contract

Input

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

Output

{
  "email": "user@example.com",
  "status": "valid",
  "reason": "ok",
  "checks": {
    "syntax": { "ok": true, "normalized": "user@example.com", "domain": "example.com" },
    "disposable": { "ok": true, "reason": null },
    "mx": { "ok": true, "checked": true, "reason": null }
  }
}

status is one of valid, invalid, or risky. reason is a machine-readable code for quick branching; checks gives the per-stage breakdown for logging/debugging.

Why MCP instead of REST

The assignment asks for a clean, well-typed tool interface another system/agent can consume — that's what MCP demonstrates directly, rather than a conventional HTTP route. Verification logic lives in its own modules independent of MCP, so a REST wrapper could be added later without touching the validation code.

Validation semantics

• invalid — definitive failures: malformed syntax, or a domain confirmed (via ENOTFOUND/ENODATA) to have no MX records at all.
• risky — the address deserves caution but there isn't enough evidence to reject it outright. Covers disposable domains, and an MX lookup that couldn't complete due to a transient DNS/network problem.
• valid — syntax, disposable-domain, and MX checks all passed.

Error handling and fail-open behavior

A DNS timeout or non-definitive resolver error is not treated as proof an email is invalid — checkMx returns checked: false and the result becomes risky, not invalid. Only a confirmed no-MX-records result is treated as definitively invalid.

The MX module also pins explicit public resolvers (8.8.8.8, 1.1.1.1) rather than trusting the OS-configured resolver — see Challenges below for why. Trade-off: this can be less suitable for corporate/VPN setups relying on internal or split DNS.

The MCP tool itself has a final defensive catch: any unexpected internal failure is converted into a structured risky result with reason: "internal_error", so a caller always gets an actionable result instead of an unhandled protocol error.

No SMTP/RCPT TO mailbox probing is attempted — MX records prove a domain can route mail, not that a specific mailbox exists. Real mailbox-level verification is slower, often blocked or rate-limited by receiving servers, and is exactly the layer a production InboxValid backend would own behind this same tool contract.

Retry/backoff is intentionally not built into verify_email — the MX check has a 2.5s timeout suitable for a real-time caller, and retrying inline would just add latency. In production, retry policy belongs to the caller (a signup form wants a fast fail; a batch job can tolerate retries), not the verification primitive.

Testing

npm install
npm test          # automated unit tests (node:test) — no live DNS needed
npm run demo       # MCP end-to-end demo: spawns the server, connects a
                   # real MCP client, lists tools, calls verify_email
npm start          # runs the server standalone (stdio, for an MCP client)

Unit tests use dependency injection — verifyEmail(email, { checkMx, checkDisposable }) accepts overrides — so DNS behavior (valid, no-MX, timeout, disposable) can be tested deterministically without a network call. npm run demo is separate and intentionally does use live DNS, since it's meant to prove the real MCP client → server → tool flow works end to end.

Project structure

inboxvalid-mcp/
├── src/
│   ├── server.js              # MCP server + verify_email tool contract
│   ├── verifyEmail.js         # orchestration (syntax → disposable → MX)
│   └── checks/
│       ├── syntax.js          # local syntax validation
│       ├── disposable.js      # mocked disposable-domain list
│       └── mx.js              # real DNS MX lookup
├── test/
│   ├── verifyEmail.test.js    # automated unit tests
│   ├── manualClient.js        # MCP end-to-end demo client
│   └── dnsDiagnostic.js       # standalone DNS troubleshooting script
├── package.json
└── README.md

Challenges faced

• OS DNS resolver was unreachable during development. Early testing on Windows returned ECONNREFUSED for every MX lookup — not because the target domains were down, but because Node's dns module couldn't reach the resolver the OS network stack was configured to use. Wrote test/dnsDiagnostic.js as a minimal standalone script to isolate the DNS layer from the rest of the tool and confirm the failure wasn't in my logic. Fixed by pinning explicit public resolvers (8.8.8.8, 1.1.1.1) instead of trusting the OS-provided one — this also turned into the real justification for the fail-open design, since it's a genuine failure mode, not a hypothetical one.
• Testing a network-dependent function deterministically. The original version of verifyEmail called checkMx directly, so the only way to test it was a live DNS call — slow, and non-deterministic in CI or on a flaky connection. Solved with lightweight dependency injection: verifyEmail accepts optional overrides for checkMx and checkDisposable, defaulting to the real implementations. Unit tests inject fake responses (timeout, no-MX, disposable) to cover every branch instantly and reproducibly, while npm run demo still uses the real DNS path to prove the actual behavior end to end.
• Deciding what "risky" should mean. A binary valid/invalid loses information: a disposable-domain address and a DNS-timeout address are both uncertain, but for different reasons, and a caller might want to treat them differently. Settled on a shared risky status with a distinguishing reason code rather than adding more status values, to keep the contract simple while still preserving that distinction.

What I'd do next with more time

• Replace the hardcoded disposable-domain set with a maintained, synced dataset — the module is isolated specifically so this is a one-file change.
• Cache MX results by domain (they change slowly) to cut lookup latency on repeat checks.
• Add rate limiting/concurrency controls around the network-bound step.

Assumptions

• "MX-style plausibility" means confirming the domain has mail routing, not proving a specific mailbox exists.
• Disposable-domain data source is mocked, per the brief's explicit allowance.