Authenticating to the MCP server
Public documentation tools need no credential. Protected Connect MCP tools use OAuth 2.1 authorization code flow with PKCE S256, protected-resource metadata, authorization-server metadata, refresh-token rotation and revocation. The grant is tied to the signed-in Connect identity, workspace, scopes and selected business. Seven scopes exist: business read and write, and five tiers for Connect operations — read, write, delete, execute and admin — of which only a workspace administrator or the Owner may grant delete, execute, admin and business write.
OAuth surface#
| Mechanism | Behavior |
|---|---|
| Protected-resource metadata | Advertises every production scope: mcp:business:read, mcp:business:write and mcp:app:read, :write, :delete, :execute, :admin |
| Authorization code | Delegated user access |
| PKCE | S256 required |
| Client type | Public client; no client secret in marketplace packages |
| Refresh tokens | Rotating |
| Revocation | Supported |
| Issuer binding | Authorization responses include iss |
| Redirect URIs | HTTPS web callbacks; HTTP only for loopback native callbacks |
| Refresh-token reuse | Presenting a refresh token that has already been rotated revokes the whole grant, so whoever held a copy loses it too |
Least privilege#
Protected-resource metadata advertises every production scope so clients can discover step-up. Individual tools still request only the minimum scope they need. Business write is a stronger permission and can read the same bound business; any Connect operations scope can search and describe the operation catalogue; and each operations tier is granted on its own — holding execute does not imply delete.
The consent page names the registered MCP client, signed-in Connect identity and selected business. Private tools then re-check their required scope and live business authority.
Scopes for Connect operations#
The operations tools sort every operation into a risk tier, and each tier has its own scope. The consent screen lists exactly the tiers the client asked for, and says that everything runs as the person, through the same checks as the app.
| Tier | Examples | Scope | Who may grant it | Confirmation |
|---|---|---|---|---|
| read | Lists, records, analytics, settings | mcp:app:read | Any member | No |
| write | Create and change records and drafts | mcp:app:write | Any member | No |
| delete | Delete, archive, merge, cancel | mcp:app:delete | Workspace admin or Owner | Yes |
| execute | Send email or WhatsApp, place or control an AI call, launch a campaign, run a workflow, give the Office Manager a task | mcp:app:execute | Workspace admin or Owner | Yes |
| admin | Product and business settings, team and roles, automation rules, mailboxes, Employees | mcp:app:admin | Workspace admin or Owner | Yes |
| financial | Subscriptions and billing | mcp:app:admin | Workspace admin or Owner | Yes |
Like the business scopes, an operations grant is bound to one business, chosen on the consent screen. Operations that work on a business receive it from the grant, never from the model; operations on the workspace itself (team, subscriptions) are still limited to that one workspace.
Public calls#
Documentation tools remain callable without OAuth because they read the public generated corpus. A bearer token does not widen a public documentation tool.
Registration and redirect rules#
Connect supports dynamic client registration for public MCP clients. A web callback must use HTTPS. A native or command-line client may use plain HTTP only on a loopback host such as 127.0.0.1, ::1 or localhost; a remote HTTP callback is refused. Redirect URIs cannot contain embedded user information or a fragment. The exact registered URI is checked again during authorization and token exchange, so accepting more than one marketplace vendor does not turn the authorization endpoint into an open redirect.
Public clients receive no client secret from registration. The authorization code is protected with PKCE S256 instead. A bad verifier consumes and refuses the code, which prevents a failed exchange from becoming a reusable credential attempt. The resource parameter is also checked against the exact MCP resource, so a code intended for Connect's MCP endpoint is not a general token for another audience.
Questions#
Do I paste an API key into an MCP marketplace package?
No. Portable packages contain no Connect credential; use OAuth.
Can native clients use localhost callbacks?
Yes. Plain HTTP is limited to loopback hosts; remote callbacks require HTTPS.
Can marketplace users request owner diagnostics?
No. Production hides both the diagnostic scope and diagnostic tool registry.