MCP / Claude agents

Overview

Install

Copy-paste install snippets, with a real API key filled in, are also available from Tools in the console sidebar. The same three options:

Claude Code CLI

claude mcp add --transport http kerabie-mail https://api.kerabie.email/mcp \
  --header "X-API-Key: YOUR_API_KEY"

Claude Desktop / any MCP client reading the mcpServers shape

{
  "mcpServers": {
    "kerabie-mail": {
      "url": "https://api.kerabie.email/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}

Test with curl

curl -X POST https://api.kerabie.email/mcp \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Authentication and scopes

Every request must carry an X-API-Key header. Missing it returns 401 before any JSON-RPC method runs. The key is resolved the same way as any other API call (get_api_key_user), and the account must be on a plan with the AI agent tools feature enabled, checked once per request.

Beyond that account-level gate, each individual tool also requires its own scope on the key, checked at tools/call time. Create the key under Settings → API Keys with whichever scopes below your agent needs:

A call to a tool the key isn't scoped for returns a JSON-RPC error (code -32603) rather than a bare HTTP 403, so a well-behaved MCP client surfaces it to the agent as a normal tool-call failure instead of a broken connection.

Tools

tools/list returns all four with their full JSON Schema input shapes, as MCP expects. The reference below is the same schema, described in prose.

send_email

Send an email from one of the authenticated account's connected mailboxes. Defaults to a sandboxed send (no real delivery, doesn't count against quota) unless sandbox: false is explicitly passed, which the MCP tool description itself tells the calling agent to only do once the user has clearly confirmed a real send is wanted.

Delegates to the same handler as POST /mail/send, so the response shape matches the Send email API reference.

list_mailboxes

No input. Lists the authenticated account's connected mailboxes, same data as the console's mailbox switcher.

search_emails

Requires either a Kerabie-managed mailbox, or a DNS-connected mailbox with a recently cached IMAP session, since an agent has no way to supply an IMAP password interactively. A DNS mailbox with no cached session returns 403; that's a hard stop for the agent, not something worth retrying.

list_recent_messages

Same IMAP-session caveat as search_emails above.

Usage examples

Using the Kerabie Mail tools, draft a short reply from support@yourdomain.com
to test@example.com confirming their refund was processed, and send it as
a sandbox test first so I can see it before it goes out for real.

Summarize the last 10 messages in my support@yourdomain.com inbox and
flag any that look urgent.

See also