MCP Server & BU Access
Connect an external AI client to one business unit with scoped tools, approval and audit.
Open interactive lesson and quizWhat you will learn
- Identify which BU an OAuth connection can access
- Grant only needed scopes and understand role checks
- Review approvals, connections and audit records
A company wants an AI assistant to inspect its Contacts and prepare a Send Flow without allowing access to another company on SupaChrome.
Lesson 1
Understand the BU boundary
The remote address https://login.supachrome.com/mcp is shared, but access is not global. An OAuth connection is created while a person signs in to one business unit and approves a named client. SupaChrome binds the token to that BU and user, checks that this BU still has MCP enabled, then checks the user is active on every request. All record tools scope their queries and writes to the token’s BU and pass through existing service validation. For example, a BU A connection cannot see BU B’s Contacts even when the client guesses a BU B record ID. Turning MCP on in BU A does not enable it in BU B. To connect BU B, a settings manager enables it there and an authorized BU B user signs in and consents separately. A platform admin login cannot serve as a shortcut into BU records.
Lesson 2
Choose scopes and review sensitive actions
In Settings → Developer & AI → MCP Server, check Allowed AI permissions for this BU and save. A client may request OAuth scopes such as contacts.read, analytics.read, audiences.write, emails.write or sendflows.write. A scope does not grant a permission missing from the signed-in user’s current BU role or object access; those permissions are checked again at use time. Removing a scope revokes connections that used it; adding one requires a new connection to consent. Read scopes permit bounded searches and reports. Write scopes allow draft audience, email and flow operations through their normal services. The MCP tool for Flow activation only creates a pending request. A BU settings manager reviews it inside SupaChrome, and the system rechecks the requester, current draft revision, audience estimate and review token before activating. Direct bulk sending and large deletes are not exposed as MCP tools. Email preview and Flow simulation do not send or modify production records. Grant only the scopes the client needs for its task.
Lesson 3
Find and count business records
Gemini CLI shows Contacts, Companies, Deals, Orders and Products as separate search tools when the corresponding read scopes are granted. The existing search_records tool also works for each object and returns up to 50 records per call. To answer “How many Contacts are in this BU?”, use records_count with object contacts. It returns an exact total scoped to the connected BU without sending contact details. An object’s read scope, current role and object access must all allow the request.
Lesson 4
Find and stop an AI connection
In Settings → Developer & AI → MCP Server, Connected AI clients shows the client name, user, scopes, last use and revocation status for the current BU. Revoke a connection to end its access, or disable the BU’s MCP switch to revoke all of its active connections. Neither action changes another BU’s settings. MCP Audit Log records successful and failed tool calls with the BU, user, client, action, affected record IDs, result, approval state and time. Use the log to investigate an unexpected draft or denied action. If a client cannot see a tool, check its consented scopes, the user’s current role, object visibility and the BU switch. The public setup guide at https://login.supachrome.com/docs/mcp lists the endpoint and supported tool groups. Practice with non-sensitive sample records before connecting a production assistant.
Practice · Connect a controlled AI client
- Sign in to a practice business unit and open Settings → Developer & AI → MCP Server. Note the BU name shown on the access card.
- Enable MCP for that BU. Under Allowed AI permissions for this BU, check contacts.read and any other needed scopes, then save.
- Choose Gemini CLI, Claude Code, Cursor, Copilot CLI, VS Code or Codex CLI in the setup card; copy the matching JSON, TOML or command. Merge it with existing client settings.
- On the consent screen, verify the BU name, your user and the requested scopes before allowing access.
- Ask the client to list tools and search a practice Contact, then check the MCP audit log.
- Revoke the connection in that same BU and confirm the client can no longer use the token.