@truval/mcp-server

v2.0.2

Published

2 months ago

Remote MCP server for truval.dev — email verify and management API tools

0High
0Medium
0Low

truval-dev

mcp truval email-verification ai-agents model-context-protocol

truval.dev mcp-server

Official Model Context Protocol (MCP) server for truval.dev — email verification and management API tools for Claude, Cursor, and other MCP-capable clients.

Most users should connect to the hosted endpoint (mcp.truval.dev). This package publishes the same Worker source to npm for self-hosting, auditing, or advanced deployments (e.g. Cloudflare Workers).

Hosted service (recommended)

| Item | Value | |------|--------| | MCP URL | https://mcp.truval.dev/mcp | | Tool schema | GET https://mcp.truval.dev/openapi.json | | Health | GET https://mcp.truval.dev/health |

No install or deploy required — configure your MCP client with the URL and headers below.

Prerequisites

Node.js 18+ — required for local development, builds, and Wrangler. (The hosted Worker does not run on your machine.)
Package manager: npm works for all commands below. pnpm is supported and recommended if you work inside the truval.dev monorepo or prefer pnpm’s workspace behavior (pnpm add @truval/mcp-server, pnpm run build, etc.).
Self-hosting on Cloudflare: a Cloudflare account and Wrangler CLI (npx wrangler or a devDependency) for deploy.

Installation (npm)

npm install @truval/mcp-server

pnpm add @truval/mcp-server

The package ships compiled ESM (dist/) with a Cloudflare Workers–style default export: { fetch(request) }. After cloning this repository (or before publishing from source), run npm run build or pnpm run build so dist/ exists — production entry is dist/index.js (see wrangler.toml). For day-to-day use, prefer the hosted URL unless you operate your own Worker.

Tools

| Tool | Purpose | |------|---------| | verify_email | Verify an email via the truval.dev API (valid, status, ordinal confidence, disposable/catch-all/smtp signals). Optional webhook for async delivery. | | create_api_key | Create a standard key (sk_live_...) using a provisioning key. | | list_api_keys | List active standard keys (no raw secret values). | | revoke_api_key | Revoke a standard key by id. | | get_usage_summary | Month-to-date usage summary (calls, tier, estimated cost). | | get_account | Account tier, limits, billing snapshot. | | get_usage | Daily usage for the last 30 days. | | create_billing_portal | Stripe Customer Portal URL (optional return_url). |

verify_email calls api.truval.dev with your standard API key. All other tools call the management API and require provisioning auth (see below).

Authentication

Send headers from your MCP client config (values are never embedded in tool arguments).

Standard API key (`sk_live_...`)

Required for verify_email (passed to the upstream verify API):

Authorization: Bearer sk_live_...

Provisioning / management (`sk_mgmt_...`)

Required for key lifecycle, usage, account, billing portal tools. The server accepts any of the following (first match wins for management auth resolution):

| Header | Notes | |--------|--------| | X-Truval-Management-Authorization | Full value, e.g. Bearer sk_mgmt_... | | X-Truval-Provisioning-Key | Raw sk_mgmt_... (server prefixes Bearer when calling the API) | | X-Truval-Management-Key | Same as provisioning key header | | Authorization | If it contains sk_mgmt_, used as management auth for those tools |

Recommended pattern: keep Authorization: Bearer sk_live_... for verify, and add X-Truval-Provisioning-Key: sk_mgmt_... so both keys can coexist without ambiguity.

Client setup

Security — never commit API keys
If you put real sk_live_... or sk_mgmt_... values (or env-expanded secrets) in .cursor/mcp.json, claude_desktop_config.json, or any file under a git-tracked project, add those paths to .gitignore (e.g. .cursor/mcp.json, or a dedicated secrets file). Teams often commit the .cursor/ folder by mistake and leak provisioning keys. Prefer environment variables in config (as below) and keep secrets out of the repo.

Cursor

Create or edit .cursor/mcp.json:

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

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

Restart Cursor. Try: verify [email protected] or verify [email protected].

Claude Desktop

Add to claude_desktop_config.json (minimum — verify only):

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

Add the provisioning header when you need management tools.

Other MCP clients

Any client that supports remote HTTP MCP can use:

POST https://mcp.truval.dev/mcp
Content-Type: application/json
JSON-RPC 2.0 body (see below).

JSON-RPC

`tools/list`

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

`tools/call` (verify)

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "verify_email",
    "arguments": {
      "email": "[email protected]"
    }
  }
}

Optional async verification:

"arguments": {
  "email": "[email protected]",
  "webhook": "https://your-app.com/truval-webhook"
}

Webhook URLs must follow truval.dev’s public API rules (HTTPS, public hostname — see API docs).

`curl` examples

# List tools (no auth required for list on hosted server)
curl -sS -X POST "https://mcp.truval.dev/mcp" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Verify (requires standard key)
curl -sS -X POST "https://mcp.truval.dev/mcp" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $TRUVAL_API_KEY" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"verify_email","arguments":{"email":"[email protected]"}}}'

Interpreting `verify_email` results

Do not rely on valid alone.

Gmail / Outlook / Yahoo: often smtp_blocked: true, confidence ~0.75 — treat as normal, not failure.
Catch-all domains: catch_all: true — lower certainty (~0.65); do not treat as proof the mailbox exists.
Unknown + MX, not smtp_blocked: SMTP inconclusive (common on org / M365); confidence often ~0.50 — confirm with the user.
Disposable: reject.
suggestion: offer a typo fix.

Full matrix: Agent decision guide.

Errors

Failures are JSON-RPC errors (error.code, error.message, optional error.data with reason, action, docs). HTTP status may mirror upstream (e.g. 429 for rate limits). See MCP integration docs.

Development

From a clone that includes this app (or after npm install / pnpm install in the package directory):

npm install   # or: pnpm install
npm run build    # emits dist/ (required before deploy; Wrangler production entry is dist/index.js)
npm run dev      # wrangler dev src/index.ts — iterate without rebuilding dist each time

Self-hosting (deploy your own Worker)

Build — npm run build or pnpm run build (Wrangler’s main is dist/index.js).
Configure — This repo includes wrangler.toml (name, main = "dist/index.js", compatibility_date, routes). For your Cloudflare account you must edit it: set a unique name, replace [[routes]] / zone_name with your hostname and zone (or use workers_dev = true for *.workers.dev while testing). Remove or change truval.dev-specific routes if you do not own that zone.
Authenticate — npx wrangler login (or use CLOUDFLARE_API_TOKEN as per Wrangler docs).
Deploy — from this directory:
```
npm run deploy
```
Equivalent:
```
npx wrangler deploy
```

The default Worker code calls api.truval.dev for verify/management; self-hosting changes where the MCP endpoint runs, not necessarily the upstream API, unless you fork and change those URLs in source.

Issues

This MCP package (tool schemas, JSON-RPC handling, docs, build): open a GitHub issue on truval-dev/truval-mcp-server (also linked from npm).
Hosted mcp.truval.dev outages, API results, or account keys: see documentation and status first.

Include client (Cursor / Claude / other), relevant headers shape (no secrets), and a redacted JSON-RPC sample when reporting integration bugs.

Pull requests

Fork and branch from main with a clear name (fix/tool-description, docs/readme).
One concern per PR; describe motivation and link issues with Fixes #n when applicable.
Build before submitting:
```
npm install
npm run build
```
Keep tool definitions and behavior aligned with MCP integration docs and the live API — avoid breaking JSON-RPC or upstream contracts without a coordinated doc/API change.

Contributing

By contributing you agree your changes are licensed under the same MIT license as this package.
Good first contributions: clearer tool description text, README improvements, and tests or examples that don’t require production secrets.

License

MIT