contact-verification-mcp

An MCP server wrapping Melissa's Global Address, Global Email, Global Phone verification APIs. Built for the SD Times / Melissa developer article "Building an MCP Server for a Verification API".

What this is

Agents can call following three tools to check whether contact data is real before acting on it; also includes a batch tool and per-session call budget to prevent agents from falling into an endless loop and incurring runaway charges:

• verify_postal_address

• verify_email

• verify_phone

• verify_batch

For design decisions behind tool descriptions, the three result types (confirmed / partially confirmed / not confirmed), and why phone line type is deliberately not exposed, see src/melissaClient.ts.

Related MCP server: email-verify

Setup

npm install
cp .env.example .env
# edit .env and set MELISSA_LICENSE_KEY to your own key
npm run build
npm start

This server communicates via MCP over stdio, so it is designed to be started by an MCP client (Claude Code, Claude Desktop, or another MCP-compatible host), not to be run standalone and interactively.

Testing

npm test          # runs entirely against recorded fixtures, no network calls, no key required
npm run typecheck  # type-checks src/ and tests/ together

Fixtures in tests/fixtures/ include a _source field: REAL indicates verbatim copies from Melissa’s published OpenAPI examples (github.com/MelissaData/MelissaCloudOpenAPI-Specifications); SYNTHETIC indicates fixtures built for test coverage because such cases don't exist in Melissa's public spec (mostly failure scenarios). Do not treat synthetic fixture result codes as if they were verified against a live account.

Running live tests

MELISSA_LICENSE_KEY=your-real-key npm run test:live

This makes real calls to Melissa’s API and consumes API credits. It is never run as part of npm test or CI. Do not commit real keys; set them as environment variables at runtime.

Results code provenance

Every Melissa result code used in this codebase (AV24, ES01, ES07, ES08, ES21, PS01, PS20, PS22) was confirmed via Melissa’s published OpenAPI spec examples—not guessed or carried over from an older article draft. Specifically:

• AV24 is the only AV-prefixed code anywhere in Melissa’s Global Address spec examples. There is no confirmed code for a separate "confirmed to subpremises" tier, so this client does not claim one.

• Global Email spec examples only show ES-prefixed codes. No EE-prefixed code appears in that spec.

• Global Phone line-type detection (mobile/landline/VoIP) is documented as Premium-only and US/CA-only, so it's not surfaced as a general capability here.

If your account's real responses include codes not in this list, that’s a sign this client needs updating—not that the new code is wrong.

What's not done yet

• Redis-backed cache for multi-instance deployments (currently in-process LRU only, see src/cache.ts).

• Line-type detection behind a feature flag for Premium-enabled accounts.

• Broader country coverage testing for Global Address beyond US/UK/DE examples in Melissa's own spec.