MCP server

Sessy ships with a built-in Model Context Protocol server, so AI agents like Claude Code, Cursor, and Codex can query your email data directly. Ask why an email bounced without leaving your editor.

The MCP server talks to your Sessy instance—it isn't a public SES API. You need either hosted Sessy or a self-hosted install, plus an API key from the dashboard. Examples below use the hosted endpoint; self-hosters swap in their own host.

Looking for the broader Amazon SES MCP landscape (send vs observe, AWS sample, etc.)? Read the overview.

What it's useful for

Typical questions you can ask from your editor once Sessy is connected.

Debugging deliverability: “Why did the email to [email protected] bounce?” The agent pulls the message timeline with bounce diagnostics.
Support lookups: “Did [email protected] receive the password reset email?” Checked while you're in the middle of a support thread.
Health checks: “What's my bounce rate this month? Any complaint spikes?” Aggregate stats per source or across your whole account.
Investigations: “Find all permanent bounces from the last week and summarize the causes.”

All tools are read-only by design. Agents can look, never touch.

How it works

Two things: an MCP endpoint on your Sessy instance, and an API key as a bearer token.

1
Point your client at the MCP endpoint

Hosted Sessy serves MCP at:
```
https://api.sessy.do/mcp
```
Self-hosted instances use the same path on your host (https://<your-host>/mcp).
2

Authenticate with an API key

Create a key under API keys in the dashboard (app.sessy.do/api_keys on hosted). Pass it as a bearer token. The dashboard also shows these setup instructions pre-filled with your endpoint.

Connect your editor

Pick your client and paste the snippet. Replace YOUR_API_KEY with a key from the dashboard.

Run this in your terminal. The next time you start Claude Code, Sessy will be available.

claude mcp add --transport http sessy https://api.sessy.do/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project), then restart Cursor.

{
  "mcpServers": {
    "sessy": {
      "url": "https://api.sessy.do/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Add to ~/.codex/config.toml, with SESSY_API_KEY exported in your shell:

[mcp_servers.sessy]
url = "https://api.sessy.do/mcp"
bearer_token_env_var = "SESSY_API_KEY"

ChatGPT custom connectors require OAuth, which Sessy doesn't support yet. It's planned for a future release.

Any MCP client that supports HTTP transport and bearer tokens can connect. Point it at your Sessy endpoint and pass an API key:

URL: https://api.sessy.do/mcp (or https://<your-host>/mcp)
Auth: Authorization: Bearer YOUR_API_KEY

Most clients use a JSON config shaped like this:

{
  "mcpServers": {
    "sessy": {
      "url": "https://api.sessy.do/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Exact file paths differ by client (VS Code, Windsurf, Claude Desktop, Zed, etc.). Check your client's MCP docs for where to paste the config.

Available tools

Four read-only tools cover sources, event search, message timelines, and aggregate stats.

list_sources: List your email sources with 30-day health stats: sent count, bounce rate, last event.
search_events: Search email events (sends, deliveries, bounces, complaints, opens, clicks) by recipient, subject, event type, or date range.
get_message: Fetch one email's full per-recipient event timeline, including bounce and complaint diagnostics.
email_stats: Aggregate stats over a date range: counts by event type, bounce/complaint/open/click rates, and daily time series.

Running behind Cloudflare or a CDN?

Bot protection (like Cloudflare's managed challenge) blocks MCP clients—they can't solve challenges. Add a WAF rule that skips bot protection for the /mcp path, or requests from your agents will silently fail.

Security notes

API keys grant read access to all of your account's email data. They live in your editor's config files, so treat them like passwords and revoke unused ones.
Email subjects, recipient addresses, and bounce diagnostics are third-party content. The server instructs agents to treat them as data, never as instructions, and tools are read-only by design.

Next steps

Hosted Sessy — sign up, create an API key, paste the snippets above
Self-host — then point clients at https://<your-host>/mcp
Connect Amazon SES if events aren't flowing yet