MCP Server

MCP endpoint

URL: https://mcp.truval.dev/mcp
Transport: HTTP (JSON-RPC)
Tools exposed: verify_email, create_api_key, list_api_keys, revoke_api_key, get_usage_summary, get_account, get_usage, create_billing_portal

The server accepts auth from the MCP client config via headers:

Authorization: Bearer sk_live_...
X-Truval-Provisioning-Key: sk_mgmt_...

Tool definition

tools/list returns { "tools": [ ... ] } with eight tools, in this order: verify_email, create_api_key, list_api_keys, revoke_api_key, get_usage_summary, get_account, get_usage, create_billing_portal.

Authoritative JSON (all names, descriptions, and inputSchema values): https://mcp.truval.dev/openapi.json

The snippet below shows only verify_email in full; the other seven tools are management and billing helpers (see Management API for the underlying HTTP API).

{
  "tools": [{
    "name": "verify_email",
    "description": "Verify if an email address is real and deliverable.\nReturns valid, status, ordinal confidence (0-1, not a probability), and signals\n(disposable, role, catch_all, smtp_blocked, typo suggestion).\nGmail/Outlook/Yahoo: smtp_blocked true, confidence ~0.75 — expected.\nCatch-all: confidence ~0.65; do not treat valid as mailbox proof.\nUnknown with MX but not smtp_blocked: SMTP inconclusive, confidence ~0.50 — ask user to confirm, do not auto-reject.",
    "inputSchema": {
      "type": "object",
      "required": ["email"],
      "properties": {
        "email": {
          "type": "string",
          "description": "The email address to verify"
        },
        "webhook": {
          "type": "string",
          "description": "Optional HTTPS webhook URL for async verification result (see POST /v1/email/verify)"
        },
        "webhook_secret": {
          "type": "string",
          "description": "Optional shared secret (min 8 characters) for webhook HMAC signing (X-Truval-Signature)"
        }
      }
    }
  }]
}

Cursor setup

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "truval": {
      "url": "https://mcp.truval.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${TRUVAL_API_KEY}",
        "X-Truval-Provisioning-Key": "${TRUVAL_PROVISIONING_KEY}"
      }
    }
  }
}

Set your key before launching Cursor:

export TRUVAL_API_KEY=sk_live_...
export TRUVAL_PROVISIONING_KEY=sk_mgmt_...

Then restart Cursor and test in chat:

verify [email protected]
verify [email protected]

Claude Desktop setup

Add server config in claude_desktop_config.json:

{
  "mcpServers": {
    "truval": {
      "url": "https://mcp.truval.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_..."
      }
    }
  }
}

Restart Claude Desktop, then test:

verify [email protected]
verify [email protected]

Other MCP clients

Any MCP client that supports remote HTTP servers can use the same endpoint and header:

Server URL: https://mcp.truval.dev/mcp
Header: Authorization: Bearer <TRUVAL_API_KEY>
Tool call shape:

{
  "name": "verify_email",
  "arguments": {
    "email": "[email protected]",
    "webhook": "https://your-server.example/truval-callback",
    "webhook_secret": "whsec_..."
  }
}

webhook and webhook_secret are optional; omit them for synchronous verification only.

How agents should interpret responses

When your AI uses the verify_email tool, instruct it on how to handle the result:

Gmail/Outlook/Yahoo will often return smtp_blocked: true and a confidence around 0.75. Your agent should consider this a passing result (do not use valid alone).
Catch-all domains will return catch_all: true (or status: "catch_all"). Even if valid is true, mailbox-level certainty is unavailable and confidence is lower (around 0.65), so your agent should apply caution.
Unknown + MX + not smtp_blocked — SMTP inconclusive on many org/M365 domains; typical confidence is 0.50. Ask the user to confirm; do not treat like undeliverable or invalid.
Disposable domains (e.g., Mailinator) will return disposable: true. Your agent should reject these.
Typo suggestions (suggestion: "[email protected]"). Your agent should ask the user to confirm the spelling.

For a full breakdown of agent decision-making, see the Agent decision guide.

Error responses

MCP stays JSON-RPC compliant. Errors are returned in error.code, error.message, and machine-actionable error.data.

Missing Authorization (-32001, HTTP 401):

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Unauthorized",
    "data": {
      "reason": "Missing Authorization header",
      "action": "Provide Authorization: Bearer sk_live_... in MCP client headers.",
      "docs": "https://docs.truval.dev/api/email-verify#authentication"
    }
  }
}

Invalid params (-32602):

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "reason": "Expected { name: \"verify_email\", arguments: { email: string, webhook?: string, webhook_secret?: string } } or another supported tool with valid arguments.",
      "action": "Provide params with a supported tool name and required arguments (e.g. verify_email requires arguments.email).",
      "docs": "https://docs.truval.dev/api/email-verify#request"
    }
  }
}

Upstream failure (-32002, HTTP mirrors upstream):

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32002,
    "message": "Upstream request failed",
    "data": {
      "status": 429,
      "body": {
        "error": "rate_limit_exceeded",
        "message": "Rate limit of 100 req/min exceeded.",
        "action": "Wait until reset_at (plus a small cushion) before retrying.",
        "limit": 100,
        "window": "1m",
        "reset_at": "2026-03-24T12:01:00.000Z",
        "docs": "https://docs.truval.dev/api/email-verify#rate-limits"
      },
      "action": "Wait until upstream reset_at before retrying.",
      "docs": "https://docs.truval.dev/api/email-verify#rate-limits"
    }
  }
}

MCP schema URL

The MCP worker also exposes:

https://mcp.truval.dev/openapi.json

This returns the MCP tool definition payload for discovery and documentation workflows.

Repository

GitHub: truval-dev/truval-mcp-server