MCP server

Connect

The endpoint is https://api.kawaa.com/mcp. Authenticate with the same API key you would use for the REST API, as an HTTP bearer token. Create one in Settings → API keys.

It uses the current stable MCP protocol (2026-07-28) over Streamable HTTP, with compatibility for deployed 2024/2025 clients. There is no vendor-specific server: every tab below reaches the same endpoint and the same tool schemas.

export KAWAA_API_KEY=ev_your_key_here

claude mcp add --transport http --scope user kawaa https://api.kawaa.com/mcp \
  --header "Authorization: Bearer $KAWAA_API_KEY"

# Check it connected
claude mcp list

export KAWAA_API_KEY=ev_your_key_here

codex mcp add kawaa \
  --url https://api.kawaa.com/mcp \
  --bearer-token-env-var KAWAA_API_KEY

# Check it connected
codex mcp list

// ~/.cursor/mcp.json: prefer this over .cursor/mcp.json inside a
// repository, which puts the key somewhere a commit can publish it.
// Cursor interpolates ${env:...}, so the key stays in your environment.
{
  "mcpServers": {
    "kawaa": {
      "url": "https://api.kawaa.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:KAWAA_API_KEY}"
      }
    }
  }
}

// Cursor will not load a newly configured server until you approve it,
// and the approval is per project. Run this once in each:
//   cursor-agent mcp enable kawaa

export KAWAA_API_KEY=ev_your_key_here

copilot mcp add --transport http \
  --header "Authorization: Bearer $KAWAA_API_KEY" \
  kawaa https://api.kawaa.com/mcp

# Check the saved server
copilot mcp get kawaa

export KAWAA_API_KEY=ev_your_key_here

grok mcp add --transport http kawaa https://api.kawaa.com/mcp \
  --header "Authorization: Bearer $KAWAA_API_KEY"

# Check it connected
grok mcp doctor

// ~/.gemini/config/mcp_config.json
{
  "mcpServers": {
    "kawaa": {
      "serverUrl": "https://api.kawaa.com/mcp",
      "headers": {
        "Authorization": "Bearer ev_your_key_here"
      }
    }
  }
}

export KAWAA_API_KEY=ev_your_key_here

# ${KAWAA_API_KEY} stays a reference; OpenClaw expands it when it connects,
# so the key never lands in the config file.
openclaw mcp set kawaa '{"url":"https://api.kawaa.com/mcp","transport":"streamable-http","headers":{"Authorization":"Bearer ${KAWAA_API_KEY}"}}'

# Check it connected
openclaw mcp probe kawaa

Or sign in instead of pasting a key

A client that supports MCP’s OAuth sign-in needs no key at all. Add the server with just the URL; the client finds Kawaa’s sign-in from the endpoint, opens a Kawaa page where you approve it, and receives a short-lived token it refreshes on its own. We have run this end to end with Claude Code and Codex:

claude mcp add --transport http --scope user kawaa https://api.kawaa.com/mcp

# Opens Kawaa's consent screen in your browser; approve, and you're connected
claude mcp login kawaa

codex mcp add kawaa --url https://api.kawaa.com/mcp

# Opens Kawaa's consent screen in your browser; approve, and you're connected
codex mcp login kawaa

• You see who is asking and for what. The approval page names the app (and says whether a domain vouches for that name or the app chose it itself), lists each permission it wants, and lets you untick any of them. By default an agent asks to verify, follow its jobs, read results and see usage.
• Some things are never on offer. A connected app can never change your plan or payment details, manage your team, change your password or keys, or delete the account, whatever it asks for.
• You can end it at any time. Settings → AI agents lists each connected app with what it may do and when it was last used. Disconnecting stops it on its next call. A connection left unused for 30 days ends on its own, and changing or resetting your password, or locking the account, disconnects every app.
• A copied token is cut off, and so is the app. Each refresh token the app is given works once. If the answer to a refresh gets lost, or the app sends several refreshes at once, it can repeat that refresh up to 5 times within 60 seconds. Any other reuse means someone else holds a copy, so Kawaa ends the connection at once for everyone holding it, and the app has to be connected again.

What the agent can do

Twelve tools, designed around what someone actually asks an agent to do rather than around the shape of the API. Seven of them read, four verify, and one stops a running job.

Five carry the protocol’s readOnlyHint, which is what a client uses to decide what may run without asking you. Two of the reads deliberately do not, because that hint is about consequence rather than price: get_email_history spends 0.5 credits, and get_job_export_link is free but writes the whole result set to storage behind an hour-long link that anyone holding it can read. Neither changes a record; both deserve the same pause as spending money. cancel_job is the one tool marked destructiveHint, so a client should ask you before it runs.

Reading

Verifying

These spend credits. Each one says its price in its own description, so the agent knows before it calls.

Stopping a job

Free, and it gives credits back. It is still marked destructive: a stopped batch cannot be resumed, so the work it abandons has to be submitted again.

Try it

Once the server is connected, ask in plain language. The agent picks the tools.

Check how many Kawaa credits I have left.

Verify sales@example.com and tell me whether it is safe to send to.

Clean the list in subscribers.csv: verify every address, then tell me
which ones to remove and which need a human decision.

Why is mail from example.com landing in spam?

The last two are also built-in prompts, clean_email_list and diagnose_deliverability, which walk the agent through the whole workflow, including budgeting, paging the results, and waiting for a bulk job properly instead of resubmitting it.

You do not need to prompt-engineer this

The server tells the agent, at connection time, that verification costs credits, which tools are free, and that catch_all and unknown are not verdicts to act on mechanically. Each tool states its own price and its own arguments. There is nothing to paste into a system prompt, and nothing that will quietly go stale in one.

The one line worth adding to your repository’s AGENTS.md or CLAUDE.md is the fact that it exists, so an agent looks for it:

Email verification, list hygiene and deliverability checks are available
through the `kawaa` MCP server. Use it rather than writing HTTP calls.

Give the key only what the agent needs

A key can be created with a list of scopes, and a scoped key is refused (with a 403 naming the scope it needed) for anything outside them. An agent doing list hygiene has no reason to reach billing, the team or the audit log, so do not hand it a key that can.

curl -X POST https://api.kawaa.com/v1/api-keys \
  -H "Authorization: Bearer $KAWAA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude Code agent",
    "scopes": ["verification:write", "verification:read", "account:read", "analytics:read"]
  }'

That list is what GET /v1/api-keys publishes as recommended_agent_scopes, and it covers every tool except check_domain_setup. Add deliverability:write if the agent should run domain checks too. Omit scopes entirely and the key is unrestricted. In the dashboard, the key form’s AI agent choice creates this same key, and Full access creates an unrestricted one.

Keeping a lid on what it spends

An agent can call an API thousands of times faster than a person can. Three things keep that from turning into a surprise on your bill.

Your plan’s rate limits apply to MCP exactly as they do to the REST API, because every tool call is a REST call made with your key. The protocol chatter around them (connecting, listing the tools, reading the reference documents) is answered inside the server and uses no credits. When it carries your key, the server checks the key with the API once and reuses the answer for a minute, so connecting uses at most one request of your rate limit. MCP also gives each key a budget of its own: 30 requests every 10 seconds and 120 a minute, whoever else shares your network address.

Reading the results properly

The server publishes a resource, kawaa://reference/verification-statuses, that explains what each verdict means, in particular the three that are easiest to misread.

• catch_all means the domain accepts mail for every recipient, so nothing could be learned about that particular mailbox. It is not a yes and not a no.
• unknown means the check could not conclude. It is often something temporary worth re-checking later.
• risky covers several unrelated situations, and sub_status says which.

Agents read that resource before interpreting results, and the built-in prompts tell them to hand these cases to you rather than deciding silently. The full status reference says the same thing for humans.

When something goes wrong

A failed tool call comes back structured, so the agent knows whether to retry, to wait, to fix its arguments, or to ask you for something.

{
  "error": {
    "kind": "payment_required",
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits. Required: 500, Available: 12.",
    "retryable": false,
    "next_step": "Top up at https://app.kawaa.com/settings/billing, then retry. Nothing was charged for this call.",
    "request_id": "b2c1…"
  }
}

That is the tool result’s structuredContent, so the discriminator is at structuredContent.error.kind rather than at the top level. The result’s one text block carries it too, for clients that show their model only text: the human-readable message and remedy first, then this object as JSON. Successful results are shaped the same way: a one-line summary, then the full result as JSON.

kind is the thing to branch on, and code is the same error code the REST API returns, so an MCP failure and an API log entry read the same.

What it does not do

• No streaming. Responses are JSON. There is no server-sent-events stream and no server-initiated messages, because nothing in the tool set needs them.
• No sessions. The server is stateless; every request stands on its own.
• Browser-based MCP clients may be blocked. The endpoint’s CORS policy, and that of the sign-in endpoints, allows Kawaa’s own origins. Command-line and editor clients, and clients that connect from a server, are unaffected.

Everything the agent can reach through MCP is also available through the REST API, and anything MCP does not cover is there.