Scope permissions

Each bearer token can be given a narrower view of your GHL account than your agency's full grant. Use this when you want a specific AI client to only see and call a focused subset of tools — for example, an inbox-triage assistant that should never touch billing, or a read-only research bot that should never write.

What scopes are

When your agency installs Agency MCP, GHL asks you to authorize a list of permissions called scopes. Examples: "View contacts", "Send messages", "Manage invoices". The full list of scopes you authorized at install is your agency's grant — your hard ceiling.

By default every bearer you create inherits the full grant. The Permissions tab lets you narrow that, per bearer, without affecting any other bearer or your agency-wide install.

You cannot enable a scope your agency was not granted at install. To add a scope to the available list, the agency owner must reinstall the marketplace app and authorize the additional permissions.

Opening the Permissions tab

The Permissions tab is in the top navigation of your dashboard, between Dashboard and Documentation. The tab loads the same way the rest of your dashboard does — through GHL's iframe sign-on. If you visit the URL directly outside of GHL, sign-on cannot complete and the page will tell you so.

Setting permissions for a bearer

Step 1. Pick a bearer from the dropdown at the top of the page. You will see all your active bearers (recently used appear first).

Step 2. Decide on a mode:

• Inherit all granted scopes (default, recommended for general-purpose AI clients) — the bearer can call anything your agency has authorized.
• Custom subset — uncheck "Inherit all" to reveal scope toggles grouped by category (Contacts & CRM, Calendars & Appointments, Conversations & Messaging, and so on).

Step 3. If you chose Custom subset, work through the categories. Each category has All and None buttons at the right that flip every checkbox in that category at once. Individual scopes can be toggled by clicking their checkbox.

Step 4. Click Save permissions. Changes apply to the next tool call from that bearer; sessions already in progress are unaffected.

Common patterns

A focused permission set narrows the surface an AI agent can affect by mistake or by prompt injection. It also gives you a clean audit trail: when something happens, you can ask "which bearer did this, and what was that bearer authorized to do?".

Permissions vs. safety mode

The Permissions tab and the bearer's safety mode (Read-only / No-delete / Full access, set when you create the bearer) are independent layers that work together:

• Safety mode caps what kinds of operations the bearer can call (read, write, destructive).
• Permissions cap which categories of GHL data those operations can touch.

Both have to allow a tool call for it to succeed. A bearer with safety mode "Read-only" and Permissions "Conversations only" can read conversations and nothing else — even if the AI requests something outside that surface.

Troubleshooting

"My AI says it can't find a tool I expected."

The tool requires a scope your bearer does not have enabled. Open Permissions, choose the bearer, and either enable the relevant scope or switch to Inherit all.

"A scope I want to enable isn't shown in the catalog."

The agency was not granted that scope at install. The agency owner must reinstall Agency MCP from the GHL marketplace and authorize the additional scope, then it will appear in the toggle list.

"I get 'permission denied' on a tool that worked yesterday."

A bearer's permissions may have been changed. Open Permissions, pick the bearer, and verify the scope the tool needs is enabled. If you switched the bearer to Inherit all, every tool the agency authorized is available again.

What's next

• Review your bearer tokens: Bearer tokens
• Connect additional AI clients with their own bearers: Connecting AI clients
• Common errors and how to fix them: Troubleshooting