End-user tools: OAuth model

What an end-user tool is

The Tool library has two tabs, and they behave completely differently. Assistant tools are connected once by your workspace and used by the assistant on everyone's behalf — one credential, one account. Your users' tools are connected by each visitor with their own account, so the assistant acts as that person upstream. This page is only about the second kind.

• A verified identity is mandatory. The connect endpoints refuse anonymous visitors. Your widget must be in a signed-in mode and the visitor must carry a widget JWT you signed — see End-user authentication (JWT). On a public widget the "Your connections" entry point does not render at all.
• One connection per (workspace, user, tool). Reconnecting replaces the stored token rather than adding a second row.
• Connect attempts are rate limited to 5 per end user per hour, per workspace.

The three OAuth client modes

Every end-user tool row carries a client mode. It answers one question: where does the OAuth client_id and client_secret come from?

• dcr — dynamic client registration (RFC 7591). Nobody registers an OAuth app. Command+K discovers the provider's registration_endpoint, then registers a client bound to our exact callback URL on the first visitor's connect and caches the resulting client ID. Requires the provider to publish that endpoint in its authorization-server metadata, and to accept our callback URL. Verified today for Linear, Notion, Atlassian, ClickUp, monday.com, Sentry, Stripe and Miro — we registered a real client with each of them from production code.
• byoc — bring your own credentials. You register an OAuth app with the provider, set its redirect URI to our end-user callback, and paste the client ID and secret. The secret is encrypted before it is stored. Your users see your app's name on the provider's consent screen, which is the right answer for white-label. Available today for all ten providers, and the only option for GitHub and Intercom.
• shared — a platform-owned OAuth app. Credentials are read from Command+K's own server environment and nothing is stored per workspace; visitors would see "Command+K" on the provider's consent screen. A preset is registered for all ten marketplace providers, but the credentials themselves are not set on this deployment, so selecting the mode fails with a clear "no managed app is configured" error. Not available today for any provider.

Per-provider table

The end-user marketplace contains exactly ten providers. Anything not in this table is not connectable per end user today.

The scope column is what Command+K actually sends on the authorize request. On the byo and shared paths that is the catalog's scope list. On the dcr path we intersect the catalog list with the scopes the provider's metadata declares, so a provider that declares no scope list gets no scope parameter and its own default grant applies. If you need a scope that is not sent, add the server as a custom end-user tool and set the scopes yourself.

The two callback URLs

Command+K has two separate OAuth callbacks, one per audience. They are not interchangeable — registering the wrong one gives you a redirect_uri mismatch at the provider, usually at the very last step of an otherwise successful flow.

• End-user (widget visitor) connections — the ten providers in the table above, and any custom end-user tool.
  Copy

  https://commandplusk.com/api/public/widget/mcp/callback

• Assistant-level (workspace-owned) connections — everything on the Assistant tools tab, including Slack.
  Copy

  https://commandplusk.com/api/public/mcp/oauth/callback

Both are derived from the origin serving the request, so if you reach Command+K on a different host, swap the origin and keep the path exactly as shown.

Where the tokens live

• Storage: one row per (workspace, end user, tool) in end_user_mcp_connections, holding the encrypted access token, the encrypted refresh token, the expiry, and the granted scopes.
• Encryption: AES-256-GCM envelope encryption. The key is derived with HKDF-SHA256 from a Command+K master secret under a dedicated domain separator, so it is cryptographically independent of the signing key that shares the same source. Envelopes are versioned, and any tamper of the IV, ciphertext, or auth tag fails the decrypt rather than returning garbage.
• Access: the table has row-level security enabled with no policies for regular database roles — every read and write goes through a server endpoint that has already verified the visitor's widget JWT. Plaintext tokens are never returned to a browser and never logged. The widget's connections list returns only display name, server URL, connection state, and timestamps.
• Lifetime and refresh: the token's own expiry is whatever the provider issued. Before a chat turn uses a tool, an expired (or within-a-minute-of-expiring) token is refreshed with the stored refresh token, and a rotated refresh token replaces the old one. If the refresh fails, the connection is marked expired and the visitor is shown a reconnect prompt instead of a broken tool call. There is no automatic deletion of idle connections — a row lives until someone deletes it, or until the workspace or the allowlist entry is deleted (both cascade).
• In-flight state: the OAuth state and PKCE verifier are stored in a separate short-lived table, valid for 10 minutes and deleted on first use, so an authorization code cannot be replayed.

Which account is connected

Providers like Linear, Notion and Atlassian ask the visitor to pick a workspace during OAuth, and the first one in the list is easy to accept by mistake. Right after a successful connect, CMD+K asks the newly connected server who it is — its get_workspace, whoami, me or viewer tool, whichever it offers — and stores the workspace or account name on the connection.

Your connections then shows that name under the provider, so "Linear · Connected · AnnounceKit · since Sep 11" instead of just "Linear · Connected". A connected row also has a Switch button: it reopens the provider's OAuth screen so the visitor can pick a different workspace or account, and the new grant replaces the old one — no disconnect-then-reconnect. Servers that expose no identity tool simply show no name; the connection works either way.

Revoking a connection

What the end user can do

1. Open the widget and click Your connections in the header (the plug icon). It appears only for signed-in visitors.
2. Click Disconnect next to the tool and confirm.
3. The stored connection row — access token, refresh token and all — is deleted immediately. Later chat turns can no longer call that tool as them; they are offered a fresh Connect instead.

What a workspace admin can do

• Revoke one connection: Dashboard → Users → open the visitor → Revoke on the connection. Owner or admin role required.
• Purge everything for a visitor: the same page offers a GDPR-style purge that deletes their conversations, messages, tool-call audit rows, MCP connections, pending OAuth state, usage counters, and plan overrides.
• Withdraw a tool from everyone: disabling or deleting the entry in Your users' tools removes it from every visitor at once — deleting it cascades away all connection rows for that tool.
• What an admin cannot do: connect a tool on behalf of a user. Authorization always happens in the visitor's own browser against their own provider account; there is no admin-side impersonation path, by design.

Setup checklist for a new provider

1. Try enabling it with no credentials first. If the provider supports dynamic registration, you are done — nothing to register, nothing to paste.
2. If it needs an OAuth app (GitHub and Intercom today), register one with the provider and set its redirect URI to exactly https://commandplusk.com/api/public/widget/mcp/callback. For Intercom, ask Intercom Customer Support to allowlist that redirect URI as well.
3. Enable the tool in Tools → Your users' tools and bind it to the assistants that should offer it. The per-widget binding decides which assistant exposes which tools.
4. Make sure the widget runs in a signed-in mode and your host page supplies a widget JWT. Without it, the connect endpoints return 403.
5. Optionally turn on prompt on open for the tool so signed-in visitors are asked to connect when the chat opens, rather than mid-conversation.