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

Why use PureBox with Claude, ChatGPT, and AI Assistants?

Connecting an assistant like Claude or ChatGPT to PureBox gives you conversational command over your inbox cleanup without compromising privacy or safety:

• Review without manual triage: Ask your assistant to summarize pending newsletters, high-volume senders, and promotional noise in seconds.
• PureBox safety guardrails: Your assistant never receives your Google password or raw Gmail OAuth credentials.
• Immutable apply plans: An assistant cannot arbitrarily delete emails. All cleanup actions require server-owned PureBox apply plans and user approval.

Why PureBox if you already have ChatGPT or Gemini?

A common question is: *"Why can't I just ask ChatGPT or Gemini to clean my Gmail directly?"*

1. Context window & memory limits: Frontier LLMs can only process a small window of text at a time. They cannot ingest and track 5,000+ emails across your entire mailbox history without running out of tokens or dropping critical details.
2. Hallucinations & silent errors: Asking a general LLM to guess what to delete without verified sender reputations leads to mistakes—like archiving an upcoming flight confirmation or miscategorizing an invoice.
3. No mailbox-level guardrails: Raw LLM prompts don't provide reversible undo history, rate limits, or account protections. PureBox indexes your inbox safely in the background, applies personalized engagement patterns, and presents reversible, review-first apply plans.

When you connect ChatGPT or Claude through Remote MCP, the assistant queries PureBox's structured guardrails rather than blindly guessing against your raw inbox.

Real-world conversational examples

Here is how you can talk to your assistant once PureBox is connected:

ChatGPT Prompts

• *"Ask PureBox for my current connection status and whether my inbox scan is complete."*
• *"Show me how many Archive and Trash suggestions PureBox found in my inbox."*
• *"What are my top 5 highest-volume email senders this month according to PureBox?"*
• *"Prepare a PureBox apply plan for my pending promotional email suggestions and summarize what will be archived."*

Claude Prompts

• *"Brief me on recurring newsletters from marketing domains in PureBox."*
• *"Check the status of my latest PureBox cleanup apply plan."*
• *"Which senders are eligible for automated cleanup in PureBox?"*
• *"Show me PureBox's recent activity history and how many emails were cleaned up."*

Cursor & Developer Assistant Prompts

• *"Check get_purebox_connection_status to verify my OAuth session."*
• *"Query get_purebox_suggestion_stats and return the breakdown of attention, archive, and trash tracks."*

How users connect in Claude, ChatGPT & Perplexity

1. Claude (Web & Desktop): Go to Settings > Connectors (or Claude Connectors Directory), click Add, enter the PureBox MCP URL (https://api.purebox.ai/mcp), and approve the OAuth login.
2. ChatGPT: Go to ChatGPT Connectors, paste https://api.purebox.ai/mcp into the Connection textbox, and authenticate with PureBox.
3. Perplexity: Visit Perplexity Connectors, click the + Custom connector button in the top-right corner, enter PureBox as the connector name, and paste https://api.purebox.ai/mcp.
4. Cursor / Windsurf: Open MCP Settings, add a new SSE/Remote server with 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

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

• Assistant access for end users
• PureBox homepage