Sessy / Docs

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.

What it's useful for

  • 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

Every Sessy instance serves an MCP endpoint at /mcp: 

https://sessy.example.com/mcp

Authentication uses an API key as a bearer token. Create one in your Sessy dashboard, which also shows these setup instructions pre-filled with your instance's actual endpoint URL.

Claude Code

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

Cursor

Add to ~/.cursor/mcp.json:

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

Codex

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

[mcp_servers.sessy]
url = "https://sessy.example.com/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.

Available tools

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.

Get started

The MCP server is included in every Sessy install, self-hosted or hosted. Self-host on GitHub or use the hosted version, then create an API key in your dashboard.