PureBox MCP

Connect ChatGPT, Claude, Cursor, GitHub Copilot, and other AI assistants to your email.

This is the canonical guide for the PureBox MCP Server: Hosted MCP Server details, Remote MCP connection flow, Model Context Protocol behavior, available tools, authentication model, and safety boundaries.

PureBox MCP

Connect ChatGPT, Claude, Cursor, GitHub Copilot, and other AI assistants to your email.

PureBox exposes the PureBox MCP Server as a Hosted MCP Server using Remote MCP via the Model Context Protocol (MCP), so MCP-capable AI assistants can perform guarded inbox-cleanup actions on behalf of a linked user - without receiving Gmail credentials or internal PureBox tokens.

Supported clients

Supported:✓ ChatGPT✓ Claude✓ Cursor✓ Windsurf✓ VS Code✓ Codex

Client-side availability can vary by app plan, platform, and MCP rollout stage.

PureBox MCP Server URL

https://api.purebox.ai/mcp

Prerequisite

The user must already have a PureBox account with Gmail connected. The MCP layer only operates on behalf of existing users; it cannot create accounts or start a Gmail OAuth flow on its own.

How users connect

  1. The user has a PureBox account with Gmail already connected.
  2. In the assistant client, the user adds the PureBox MCP server URL: https://api.purebox.ai/mcp.
  3. The client fetches GET /.well-known/oauth-protected-resource, follows the OAuth 2.1 authorization challenge via WorkOS AuthKit, and obtains a resource-bound bearer token.
  4. PureBox maps the verified identity to the existing PureBox user and records the assistant link on the first verified tool call.
  5. The user can list and revoke linked assistants from Account > Assistant access.

Note: connection requires an MCP client that supports a Hosted MCP Server over Remote MCP with OAuth. Desktop clients such as Cursor, Claude Desktop (with a servers config), and ChatGPT with configured Connectors are examples of capable clients.

Available tools

ToolPurpose
get_purebox_connection_statusReports assistant link and Gmail connection state.
start_purebox_scanStarts or resumes a non-destructive inbox scan.
get_purebox_scan_statusReturns scan progress, blockers, and apply options.
get_purebox_suggestion_statsReturns aggregate stats for the current suggestion cohort.
list_purebox_suggestionsLists individual suggestions (same cohort as the web app).
search_purebox_sendersSearches user-scoped sender data.
get_purebox_sender_briefingReturns sender insight and pending-message context.
get_purebox_activity_summaryMirrors recoverable history, redacting secrets.
prepare_purebox_apply_planCreates a bounded, immutable apply plan.
apply_purebox_apply_planApplies a server-owned plan idempotently.
get_purebox_apply_statusReturns apply progress and outcome.
get_purebox_automation_candidatesLists senders eligible for opt-in automatic cleanup (Pro).
enable_purebox_automationEnables automatic cleanup for a sender (Pro, with consent check).
send_purebox_assistant_feedbackSends feedback about a tool interaction.

Authentication model

PureBox uses a two-layer model that keeps concerns strictly separated.

Layer 1 - Assistant to PureBox. The assistant presents a resource-bound OAuth 2.1 bearer token issued by WorkOS AuthKit. PureBox verifies the signature against the authorization server's JWKS. A missing, expired, or invalid token returns 401 invalid_token with an RFC 6750 WWW-Authenticate challenge.

Layer 2 - PureBox to Gmail. PureBox uses the user's stored Google OAuth connection. If Gmail is disconnected, the tool result carries a needs_user_action outcome with a safe deep link back to PureBox - never a 401 transport error.

These layers never mix: a bearer token failure is never surfaced as a user task, and a Gmail connection issue is never surfaced as a token error.

Outcome envelope

Every tool result uses a shared JSON envelope:

{
  "outcome": "ok | needs_user_action | blocked | transient",
  "data": {},
  "issue": {
    "code": "MACHINE_CODE",
    "title": "Human title",
    "detail": "...",
    "remediation": "Imperative action for the assistant to narrate to the user",
    "action_url": "https://purebox.ai/...",
    "retryable": false
  }
}

A non-ok outcome always carries issue. A transient outcome is always retryable: true.

Security guarantees

  • Gmail credentials and OAuth tokens are never shared with any assistant.
  • Assistant tokens are resource-bound to https://api.purebox.ai/mcp and are unusable against the regular PureBox API.
  • Apply plans are server-owned and immutable; assistants cannot construct arbitrary Gmail operations.
  • Write paths (apply, enable automation) require the same Pro entitlement and consent checks as the web app.
  • An unconfigured deployment rejects all MCP traffic by default.
  • Revoking an assistant link from Account does not affect the user's Gmail connection.

Discovery endpoint

GET https://api.purebox.ai/.well-known/oauth-protected-resource

Returns the RFC 9728 protected resource metadata document: authorization server URL, supported scopes, and resource indicator.

See also