Available in v2.4.0 and matching MCPBridge. MCPHub must use its built-in issuer with client authorization enabled. Sign in with local accounts, LDAP or OIDC; your account must be enabled and have group access.

Connect using a link

mcpbridge pair start --server https://hub.example.com/mcp --profile work --name "Project Agent" --json
  1. Show the user the returned verification_uri_complete and user_code. The link contains only the public comparison code.
  2. Open the link in the user's browser, sign in and compare the code. The requester supplies the client name; it is not a verified application identity.
  3. Choose a service and specific tools, then narrow resource restrictions and duration. No tools are selected by default; write access is off by default.
  4. Approve access and return to the Agent to collect credentials and check connectivity.
mcpbridge pair finish --request pr_example --wait --json
mcpbridge connect --profile work --client ci_example

Replace the request and client IDs with the actual results. Without --wait, finish checks once. pending_user requires browser approval; ready means private credentials were saved and MCP connectivity was checked. Denied, expired or failed deliveries require an explicit new request. Never copy passwords or tokens to your Agent.

Switching languages preserves your service, tools, duration and resource restrictions. Write access is shown only when requested and eligible tools exist. If a code is invalid or expired, start a fresh request in your Agent and enter its new code on the same page. Invalid resource restrictions do not end the request; correct the form and submit again.

Agents without command execution

Use the actual absolute MCPBridge executable path in the client's stdio configuration, with these arguments:

["connect", "--server", "https://hub.example.com/mcp", "--profile", "work", "--name", "Project Agent", "--interactive-auth"]

The local session initializes immediately. Call mcpbridge_auth_start for a link and comparison code, then mcpbridge_auth_status at the returned interval. Status may collect credentials, save them and check connectivity. Only these two authentication tools exist before approval; business calls are never queued.

Refresh tools after ready. MCPBridge sends notifications/tools/list_changed. If your Agent cannot refresh, reconnect with the returned connect --profile … --client … arguments. Revocation, expiry or lost group access requires explicit reauthorization. Failed business operations are never automatically retried.

Servers and containers

Run MCPBridge and both pairing commands on the Agent's machine. Users can open the link on their own computer; no browser callback to the remote machine is needed. Use the same operating-system user and private directory. MCPHUB_HOME selects a persistent directory; mount a private volume in containers. A public request ID alone cannot collect credentials.

Limits and troubleshooting

The request, confirmed grant and Broker session must remain valid when credentials are collected. After expiry, start pairing explicitly again. A completed request cannot cancel its delivered login session; revoke clients through authorization management. Current access is checked on every business request, so revocation blocks calls immediately without waiting for an Agent status refresh.

Each grant covers one service; pair separately for additional services. Current group access always applies, and newly published tools never expand existing grants. Requests expire after 5 minutes, polling starts at 5 seconds, and the default requested maximum lifetime is 1 hour, capped by the gateway. Narrow requests with --endpoint, repeated --tool / --scope, and --ttl seconds (at least 60). --allow-write-requests requests optional write access, still subject to browser consent and existing approvals.

This flow grants tool capability only. Use existing setup / client add for prompts, resource URIs or subscriptions. Use a separate profile for another user or server. Failed pairing preserves an existing working profile. For a pure external issuer, use the existing PKCE setup wizard.