tvram-backend-mcp

An MCP server that exposes email verification as a tool an agent can call.

verify_email(address) -> { address, verdict: valid | invalid | risky, reason }

Assumptions

• We only design and build the mcp servers and not the actual logic and implementation behind the email verification .
• MCP auth needs to be handled ( a demoable piece and not actual auth for now) , just a visual representation of it works .

The tool contract

This is what a model actually receives, from a live tools/list:

{"name": "verify_email",
 "description": "Check whether an email address can receive mail. Returns a verdict of
   \"valid\" (well formed and not flagged), \"invalid\" (malformed, mail cannot be
   delivered), or \"risky\" (well formed but on a disposable provider, so delivery is
   unreliable), together with the reason the verdict was reached. Accepts one address
   per call.",
 "inputSchema": {"type": "object", "additionalProperties": false,
                 "properties": {"address": {"type": "string"}},
                 "required": ["address"]},
 "outputSchema": {"type": "object",
   "properties": {
     "address": {"type": "string", "description": "The address that was checked, lowercased."},
     "verdict": {"type": "string", "enum": ["valid", "invalid", "risky"],
                 "description": "valid: syntax is well formed and the address looks
                   deliverable. invalid: syntax is malformed, the address cannot receive
                   mail. risky: syntax is well formed but the domain is a disposable
                   provider, so delivery is unreliable."},
     "reason":  {"type": "string", "description": "Which rule produced the verdict."}},
   "required": ["address", "verdict", "reason"]}}

Results come back as structuredContent, so an agent branches on verdict without parsing prose:

{"address": "alice@example.com",    "verdict": "valid",   "reason": "syntax is well formed and the domain is not flagged"}
{"address": "not-an-email",         "verdict": "invalid", "reason": "address does not match the expected email syntax"}
{"address": "alice@mailinator.com", "verdict": "risky",   "reason": "mailinator.com is a disposable email provider"}

Design choices

• Reason for all result irrespective of valid/risky/invalid .
• Standalone service that can be run .

Error handling

• Return only user related errors and not system internal errors, in case of system error just return internal server error

Retry and backoff

MAX_RETRIES = 2 with 0.25 * 2**attempt — three attempts over roughly 0.75s of waiting.

• Only 5xx errors are retried since its related to the sever handling whereas 4xx errors means the user/api input is not valid .

Setup

Requires Python 3.12+ and uv.

uv sync
uv run python mock_server.py    # mock backend       on 127.0.0.1:8000
uv run python mcp_server.py     # MCP server

Copy .env.example to .env to change anything; every value there is already the built-in default, so it runs with no configuration at all.

Connecting an agent

With both servers running:

claude mcp add --transport http tvram-email-verification http://127.0.0.1:8001/mcp

Then /mcp → select the server → Authenticate. A browser opens a consent screen; approving redirects back and the connection completes.