Email verification in MCP

npm install @modelcontextprotocol/sdk zod

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "zapbounce", version: "1.0.0" });
const KEY = process.env.ZAPBOUNCE_KEY!;

server.tool(
  "verify_email",
  // The description is a prompt. Tell the model what each verdict means, or it
  // will treat catch-all as valid and tell your user the address is fine.
  `Verify one email address. Returns a status of one of four values:
   valid (the mailbox accepted it), invalid (permanently rejected),
   catch_all (the DOMAIN accepts every address, so the mailbox is unconfirmable),
   unknown (the server refused to answer; its credit is refunded, and it is not a judgment).
   A flags array comes back beside the status: role (a shared function mailbox
   such as info@), disposable (a throwaway provider) and free_provider. A flag is not a status.
   Never report catch_all or unknown to the user as confirmed.`,
  { email: z.string().email().describe("The address to verify") },
  async ({ email }) => {
    const res = await fetch("https://app.zapbounce.com/api/v1/verify", {
      method: "POST",
      headers: { "X-API-Key": KEY, "Content-Type": "application/json" },
      body: JSON.stringify({ emails: [email] }),
      signal: AbortSignal.timeout(15_000),
    });

    if (!res.ok) {
      const err = await res.json();   // { statusCode, code, message, requestId }
      return {
        isError: true,
        content: [{ type: "text", text: `${err.code}: ${err.message}` }],
      };
    }

    const { results } = await res.json();
    const r = results[0];
    return {
      content: [{
        type: "text",
        text: `${r.email}: ${r.status} (reason ${r.reasonCode}, smtp ${r.smtpCode ?? "none"}, ` +
          `flags: ${r.flags.join(", ") || "none"})`,
      }],
    };
  },
);

await server.connect(new StdioServerTransport());

server.tool(
  "verify_list",
  `Submit up to 50,000 addresses for background verification. Returns a job id
   immediately; call check_job to see progress. valid, invalid and catch_all
   cost one credit each. The credit for an unknown result is refunded.`,
  {
    emails: z.array(z.string().email()).min(1).max(50_000),
  },
  async ({ emails }) => {
    const res = await fetch("https://app.zapbounce.com/api/v1/jobs", {
      method: "POST",
      headers: {
        "X-API-Key": KEY,
        "Content-Type": "application/json",
        "Idempotency-Key": crypto.randomUUID(),
      },
      body: JSON.stringify({ emails, source: "api" }),
    });
    const job = await res.json();
    return {
      content: [{
        type: "text",
        text: `Job ${job.id} queued. ${job.totalEmails} addresses submitted.`,
      }],
    };
  },
);

server.tool(
  "check_job",
  "Progress and verdict breakdown for a job. Report every count, not just the valid ones.",
  { job_id: z.string() },
  async ({ job_id }) => {
    const j = await fetch(`https://app.zapbounce.com/api/v1/jobs/${job_id}`, {
      headers: { "X-API-Key": KEY },
    }).then((r) => r.json());

    // There is no webhook: the model asks again until the status is terminal.
    if (!["completed", "partial", "failed", "cancelled"].includes(j.status)) {
      return { content: [{ type: "text", text: `${j.status}. Ask again in a few seconds.` }] };
    }
    // Every count next to the total, every time. A summary with only the valid
    // count invites the model to report it as though it described the whole list.
    return {
      content: [{
        type: "text",
        text: [
          `${j.status}. ${j.totalEmails} addresses.`,
          `valid ${j.validEmails}, invalid ${j.invalidEmails},`,
          `catch-all ${j.catchAllEmails} (domain accepts everything),`,
          `unknown ${j.otherEmails} (no verdict, credit refunded).`,
        ].join(" "),
      }],
    };
  },
);

// claude_desktop_config.json — the key stays in the server process, never in
// the conversation. An assistant that can read the key can leak it in a reply.
{
  "mcpServers": {
    "zapbounce": {
      "command": "node",
      "args": ["/absolute/path/to/zapbounce-mcp/index.js"],
      "env": {
        "ZAPBOUNCE_KEY": "zb_live_..."
      }
    }
  }
}

// For anything a model triggers on its own, use a key with only the scopes the
// tools call: verification.run, jobs.view and jobs.manage. Leave credits.view
// off unless you add a balance tool, so a mistake cannot reach further than it must.