Connect an AI client

Use SupaChrome's remote MCP server with your business account and OAuth.

Which Business Unit can it access?

Only the BU used during SupaChrome sign-in and consent. The URL below is shared by all businesses; it does not grant platform-wide access. SupaChrome stores the BU and user on the OAuth connection, checks the user's current role and object permissions for each tool call, and scopes every record operation to that BU.

For example, enabling MCP in BU A does not enable it in BU B. An AI client connected while signed in to BU A cannot query BU B. To work in BU B, its settings manager must enable MCP there and an authorized BU B user must complete a separate sign-in and consent. A platform admin login is not a BU data connection.

Set up your BU

Sign in to the intended BU at login.supachrome.com.
In that BU, open Settings → Developer & AI → MCP Server and enable it. Under Allowed AI permissions for this BU, check the scopes the AI client may use and save. The switch and policy affect only this BU.
Choose your client below, copy its JSON, TOML or command, and merge it with your existing settings. The endpoint is https://login.supachrome.com/api/mcp. If you previously copied a configuration ending in /mcp, replace that URL.
Complete SupaChrome OAuth sign-in, check the BU and client name on the consent screen, and allow only the scopes needed for your work.
Return to the same Settings screen to review connected clients, revoke a connection, see audit activity, or approve a requested Flow activation.

The examples below start with contacts.read. The signed-in BU screen generates Gemini CLI JSON from the scopes selected for that BU. At consent, SupaChrome shows the scopes your role and BU actually allow, even if the client requests more. Other clients request the allowed scopes your role grants when they do not specify a scope. Removing a scope revokes connections using it; reconnect to gain newly allowed scopes. No database credentials or integration key are required.

Connect your AI client

Choose your tool, copy its setup, then sign in to this BU when the tool opens SupaChrome. No API key or password goes in the config.

Add to ~/.gemini/settings.json

{
  "mcpServers": {
    "supachrome": {
      "httpUrl": "https://login.supachrome.com/api/mcp",
      "oauth": {
        "enabled": true,
        "scopes": [
          "contacts.read"
        ]
      }
    }
  }
}

Merge the mcpServers entry into your existing settings. In Gemini CLI, run /mcp auth supachrome when prompted.

The SupaChrome sign-in grants scopes selected for this BU that your role permits when the client does not specify scopes. Gemini CLI config includes this BU's selected scopes. Keep your other servers and settings in the file.

Available tools and permissions

A scope allows a client to ask for an operation. The user must also have the matching BU role and object access at the time of the call. Tools cannot run unrestricted SQL.

Gemini lists named Contacts, Companies, Deals, Orders and Products search tools when your connection has each object’s read scope. With contacts.write, contacts_create accepts a name and email, with optional Contact fields, and creates one record in the signed-in BU. audiences_create, emails_create_draft and sendflows_create_draft offer short inputs for common creation tasks. The existing save tools support full definitions and later edits. Use records_count for an exact BU-scoped total; search_records remains available for existing clients and returns only a limited page of records.

Work	Required scope
Discover schemas and search Contacts, Companies, Deals, Orders, Products	The corresponding object read scope
Create a Contact	contacts.write and Contact create access
Read analytics, campaigns, content, coupon claims	analytics.read, campaigns.read, content.read, coupons.read
Read or save Audiences, Emails and draft Send Flows	Their read or write scopes
Request Send Flow activation	sendflows.activate and in-app approval

Email previews never send; Flow simulation never changes production data. Bulk sends and large deletes have no direct MCP tool. Flow activation creates a pending approval that a BU settings manager reviews and SupaChrome rechecks before activation.

Learn and troubleshoot

Read the dedicated MCP and BU access Academy path for a guided example. The Coupon Redemption path covers ecommerce/POS events and claim history.

After you allow the connection, the browser should open a localhost callback on the computer running your AI client. If it stays on SupaChrome, use the Complete connection button shown there while the CLI is waiting. If the CLI timed out, run /mcp auth supachrome again to start a fresh request; reusing an old approval form shows “expired.”

The server supports stateless Streamable HTTP JSON-RPC with initialize, ping, tools/list and tools/call. Each POST requires an OAuth Bearer token. Access tokens expire after one hour; refresh tokens rotate. If a tool is missing or denied, check the consented scope, current BU role, object permissions and the BU's MCP switch.