# 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.

- **Status:** Available
- **Audience:** developer
- **Last verified:** 2026-09-30
- **Canonical:** https://connectbyjbrh.com/developers/mcp-authentication/

## OAuth surface

| Mechanism | Behavior |
|---|---|
| Protected-resource metadata | Advertises both production business scopes: read and write |
| 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 |

## Least privilege

Protected-resource metadata advertises every production business scope so clients can discover read and write 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. Offline access is requested separately when needed. Production authorization does not advertise or grant owner diagnostic scope.

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.

## 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.

> **Note** Origin validation is a separate browser-safety control; it is not OAuth identity.

## 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 is not a scope every signed-in member can consent to. The OAuth layer permits that scope only for live Owner or workspace-admin authority. The tool layer then checks again before a write. This repeated check is deliberate: scope answers what the client was granted, while live role answers whether the person still holds the organizational authority that made the grant valid.

## 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.

## Related

- [The Connect MCP server](https://connectbyjbrh.com/developers/mcp-server/)
- [Workspace MCP tools](https://connectbyjbrh.com/developers/mcp-workspace-tools/)
- [Integration keys](https://connectbyjbrh.com/developers/integration-keys/)
- [OAuth for agents](https://connectbyjbrh.com/docs/protocols/oauth-for-agents/)

## What this page is based on

- `backend/app/mcp_oauth.py`
- `backend/app/integration_auth.py`
- `backend/app/mcp_server.py`