Verify, enrich and screen from inside an agent
Sortance speaks the Model Context Protocol. Point any MCP client at one URL with your API key and the agent can check an address before it sends, look up who is behind it, screen a signup for a typo’d address or a fake name, or run the free syntax, MX and disposable-domain checks alone, with no integration code. It can also set your rules: tell your own Claude “block all non business emails” and it writes, checks and saves the policy for you.
The endpoint
https://api.sortance.com/mcp- Transport: Streamable HTTP, stateless. Every request is one POST and one JSON response. There is no SSE stream and no session.
- Auth: either sign in with OAuth (Claude, ChatGPT and other apps that add connectors by URL; see below), or send the same
Authorization: Bearer sk_live_...header as the REST API. A key comes from the quickstart.
Connect a client
Claude, ChatGPT and other apps: sign in
Apps that add MCP servers as connectors, such as Claude (web and desktop) and ChatGPT, connect by signing in. No key to copy.
- In the app, add a custom connector (MCP server) with the URL
https://api.sortance.com/mcp. If it asks how to authenticate, choose OAuth. - The app opens Sortance. Sign in, pick the organisation, and choose Full or Read-only access.
- Click Allow. The app is connected and can use the tools below.
A connected app acts as you in that organisation, with at most member rights: it can run checks and change rules, never manage keys or members. If you are a viewer, or choose Read-only, it can only read. Removing you from the organisation disconnects it at once. See and disconnect apps under Settings → API keys → Connected apps. Its checks count against the organisation’s quota like any key.
For client developers: the server follows the MCP authorization spec. A request without a token gets 401 with WWW-Authenticate pointing at /.well-known/oauth-protected-resource/mcp; the authorization server metadata is at https://api.sortance.com/.well-known/oauth-authorization-server. It supports dynamic client registration and client ID metadata documents, authorization code with PKCE (S256) only, rotating refresh tokens, and scopes mcp and mcp:read. Access tokens last an hour and work only on /mcp.
Claude Code
claude mcp add --transport http sortance https://api.sortance.com/mcp \
--header "Authorization: Bearer $SORTANCE_KEY"Clients configured with JSON (Cursor, VS Code, others)
{
"mcpServers": {
"sortance": {
"type": "http",
"url": "https://api.sortance.com/mcp",
"headers": { "Authorization": "Bearer sk_live_..." }
}
}
}A config file checked into a repository publishes its key to everyone who can read that repository. Use your client's environment-variable substitution where it has one, or a local scope that is not committed.
Tools
verify_email
Runs the same pipeline as POST /v1/verify and returns the same payload, so the result has a calibrated bounce_probability, its interval, a recommendation, the actor class and the provider evidence. Each call counts as one verification against your monthly quota.
| Argument | Type | Notes |
|---|---|---|
email | string | Required. Up to 320 characters. |
purpose | string | signup, outbound or list_hygiene. |
sender_domain | string | The domain you will send from. |
max_cost_usd | number | Spend ceiling for this call. |
max_latency_ms | number | Latency ceiling for this call. |
enrich_contact
Runs the same lane as POST /v1/enrich and returns the EnrichmentProfile, with the person and company, coverage and sources. Consumer mailboxes skip paid lookups. It is not counted against the verification quota.
| Argument | Type | Notes |
|---|---|---|
email | string | Required. |
fields | string[] | person, company, or both. Omit for both. |
strategy | string | waterfall (default) or fanout. |
max_cost_usd | number | Defaults to $0.10. |
max_latency_ms | number | Defaults to 3000. |
screen_contact
Runs the same code as POST /v1/screen and returns the same screening response: a typo suggestion, how the address relates to the name, whether the name looks real, whether the domain looks like a lookalike, placeholder or throwaway (domain_check, judged from the domain name alone), and allow or review. Each call counts as one screening against the separate screening allowance, not against verifications.
| Argument | Type | Notes |
|---|---|---|
email | string | Required. Up to 320 characters. |
name | string | Optional. The name the person typed, up to 200 characters. Without it, the name is not checked; the address checks and the domain check still run. |
check_email
Runs the same checks as POST /v1/check and returns the same object: syntax, MX, Sortance’s disposable lists and your own domain and address rules, with passes, the check reasons and email_type. No provider is called and no bounce probability is given. It is free: not counted against any quota.
| Argument | Type | Notes |
|---|---|---|
email | string | Required. Up to 320 characters. |
Set rules from your AI client
Six more tools let your AI client change what Sortance allows or blocks for your organisation. Your client does the writing, on your own AI plan; Sortance validates every rule with the same checks the dashboard uses. Ask in plain English, for example “block all non business emails”, “send role accounts to review” or “block competitor.com”.
| Tool | What it does | Role |
|---|---|---|
get_policy_context | The rule reference (fields, operators, the email types, worked examples), your list names and the active rules. The client reads this first. | viewer |
check_policy_draft | Validates a draft policy and replays it over your recent decisions. Saves nothing. | member |
save_policy_draft | Saves the draft as a new version, not active. You can review it under Rules → Policy. | member |
activate_policy_version | Makes a saved version live. The tool tells the client to ask you first. | member |
list_blocklist | Your domain or address blocklist or allowlist. Addresses are shown masked. | viewer |
update_blocklist | Adds or removes domains or single addresses, up to 1,000 per call. Takes effect immediately. | member |
The Email types card on the Policy screen is the r_type_* rules in your default policy, so a change made from your AI client shows up there, and the other way round. See policies and blocklists.
Errors
A tool that ran and failed returns a result with isError: true, carrying the same { error: { code, message, trace_id } } envelope as the REST API. Examples are an invalid address, quota_exceeded, screening_quota_exceeded or internal_error. The agent can read it and decide what to do. A missing or invalid key is an HTTP 401 before any tool runs. The rate limit is the verify limit, shared with the REST API (see going to production).
Every result carries a trace_id: vr_ for verifications, en_ for enrichment and sc_ for screenings. Report a bounce against a vr_ id with POST /v1/outcome exactly as you would for a REST call.