Connect by JBRH Open Connect

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.

Status
Available What this means
Audience
developer
Last verified
Product version
6.3.2

OAuth surface#

MechanismBehavior
Protected-resource metadataAdvertises every production scope: mcp:business:read, mcp:business:write and mcp:app:read, :write, :delete, :execute, :admin
Authorization codeDelegated user access
PKCES256 required
Client typePublic client; no client secret in marketplace packages
Refresh tokensRotating
RevocationSupported
Issuer bindingAuthorization responses include iss
Redirect URIsHTTPS web callbacks; HTTP only for loopback native callbacks
Refresh-token reusePresenting 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.

TierExamplesScopeWho may grant itConfirmation
readLists, records, analytics, settingsmcp:app:readAny memberNo
writeCreate and change records and draftsmcp:app:writeAny memberNo
deleteDelete, archive, merge, cancelmcp:app:deleteWorkspace admin or OwnerYes
executeSend email or WhatsApp, place or control an AI call, launch a campaign, run a workflow, give the Office Manager a taskmcp:app:executeWorkspace admin or OwnerYes
adminProduct and business settings, team and roles, automation rules, mailboxes, Employeesmcp:app:adminWorkspace admin or OwnerYes
financialSubscriptions and billingmcp:app:adminWorkspace admin or OwnerYes

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.

Token lifetime, rotation and live authority#

Access and refresh values are opaque credentials; the raw access token is not stored as a database primary key. Refresh tokens rotate when used, and revocation is a first-class endpoint rather than an instruction to wait for expiry. More importantly, token verification rechecks the user's workspace membership and role instead of assuming that authority remains true until the token expires. Removing a membership therefore invalidates the delegated path on a later request.

Business write and the delete, execute and admin operations scopes are not scopes every signed-in member can consent to. The OAuth layer permits them only for live Owner or workspace-admin authority, and token verification checks the role again on every request: a member who holds one, or an administrator demoted after consenting, has the token revoked on its next use. Scope answers what the client may ask for; the live role answers whether the person may still delegate it.

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.