PureBox MCP server

Connect an AI assistant to PureBox with MCP

Use PureBox from an AI assistant that supports remote MCP servers. Your assistant can ask PureBox about scans, suggestions, senders, History, and guarded cleanup plans while PureBox keeps your Gmail login and tokens private.

Create PureBox accountSee assistant access

Check these first

The PureBox server is ready, but your assistant app must support adding remote MCP servers with OAuth. If that setting is not available in your assistant, keep using the PureBox web app until your assistant client adds support.

  • An existing PureBox account
  • Gmail connected in PureBox
  • An assistant or client that supports remote MCP servers with OAuth

Server details

MCP server URL
https://api.purebox.ai/mcp
Protected resource discovery
https://api.purebox.ai/.well-known/oauth-protected-resource
Transport
Streamable HTTP JSON-RPC over MCP.

Why OAuth matters

PureBox treats MCP as a protected resource. Your assistant gets a resource-bound token for PureBox MCP, not your normal PureBox web session, not your Gmail OAuth token, and not your Google password.

How to connect

Exact labels vary by assistant client. The safe sequence is the same: add the server, authorize PureBox, then ask for status before asking for cleanup.

  1. 01

    Open your assistant client settings

    Look for a connectors, integrations, tools, or MCP servers area. If your app does not expose remote MCP server settings, it cannot connect yet.

  2. 02

    Add the PureBox MCP server

    Use https://api.purebox.ai/mcp as the remote MCP server URL. Compatible clients can discover the protected resource and OAuth challenge automatically.

  3. 03

    Authorize with your PureBox identity

    Complete the OAuth sign-in and consent flow with the Google identity already connected to PureBox. PureBox links existing accounts only.

  4. 04

    Ask for connection status first

    Start with: "Ask PureBox for my connection status." If Gmail needs attention, your assistant should give you a safe PureBox link instead of retrying auth.

What your assistant can do

Check readiness and scans

Ask whether PureBox is connected, start or resume a non-destructive scan, and check scan progress before cleanup is available.

get_purebox_connection_status, start_purebox_scan, get_purebox_scan_status

Review cleanup context

Ask for suggestion counts, a page of suggestions, sender context, or recent History so the assistant can brief you before action.

get_purebox_suggestion_stats, list_purebox_suggestions, search_purebox_senders, get_purebox_sender_briefing, get_purebox_activity_summary

Use guarded PureBox actions

Prepare and apply bounded cleanup plans, check apply status, review automation candidates, enable automation when your account allows it, and send feedback.

prepare_purebox_apply_plan, apply_purebox_apply_plan, get_purebox_apply_status, get_purebox_automation_candidates, enable_purebox_automation, send_purebox_assistant_feedback

Starter prompts

  • Ask PureBox for my connection status.
  • Start a PureBox scan if my account is ready.
  • Show me how many Archive and Trash suggestions PureBox found.
  • Brief me on newsletters from example.com in PureBox.
  • Prepare a PureBox apply plan for pending Archive suggestions.
  • Check the status of my PureBox apply plan.

Safety model

  • No Gmail OAuth tokens, Supabase tokens, refresh tokens, or passwords are returned to the assistant.
  • PureBox links existing accounts only. It does not create an account from an assistant call.
  • Gmail problems return a safe PureBox account link, not an assistant auth loop.
  • You can revoke assistant access in Account without disconnecting Gmail.

Troubleshooting

  • No MCP setting: your assistant client cannot connect yet.
  • Authorization repeats: reconnect the server and use the same Google identity you use for PureBox.
  • Gmail needs action: open the PureBox link your assistant returns and reconnect Gmail.
  • Apply is blocked: ask for the apply status or review plan, entitlement, and consent state in PureBox.

FAQ

Can I connect ChatGPT or Claude to PureBox?

Yes when the ChatGPT, Claude, or other assistant client you are using supports adding remote MCP servers with OAuth. If your app does not expose that setting yet, the PureBox MCP server is ready but that app cannot connect to it yet.

Does my assistant get my Gmail password or Google tokens?

No. PureBox keeps Gmail OAuth tokens and Supabase tokens inside PureBox. The assistant receives a resource-bound MCP token for the PureBox MCP resource, not your Gmail credentials.

Can an assistant delete my emails directly?

No assistant gets arbitrary Gmail access. Cleanup writes must go through PureBox-owned apply plans, idempotency keys, account checks, entitlement checks, and status tracking. Recovery still happens in Gmail.

What if my assistant says PureBox is not connected?

Ask for PureBox connection status first. If Gmail needs attention, the tool result should include a safe PureBox account link. If assistant authorization fails, reconnect the MCP server from the assistant client.