User sessions

User sessions answer the question of who is calling an MCP server. The platform acts as the OAuth authorization server for the server’s endpoint: MCP clients discover it, register with it, send their user through a login and a consent screen, and receive a token scoped to that server.

Every tool call then carries a subject, the person behind the agent, and a client ID, the agent itself, so calls can be attributed to the MCP client that made them. Once a caller is identified, the server’s team access rules decide whether they may connect and which tools they reach.

User sessions are configured on the server detail page, reached from MCP Gateway > MCP in the project sidebar. See Access, OAuth, and sessions for how they fit with upstream credentials and team access.

Access requirements

Viewing a server’s authentication settings requires the mcp:read scope and changing them requires mcp:write. Revoking sessions and client registrations requires project:write, which only the default Admin role includes.

What turns it on

User sessions turn on once the server has an identity provider set up: User Identity on a remote server, or Set up authentication on a hosted or tunneled server or a gateway. See Where authentication is configured for where each server type keeps the setting. The detail sidebar’s Readiness checklist reports the state under Authentication.

A public tunneled server is the exception. It skips the gate entirely and serves anonymous callers, as described in Anonymous access.

What an MCP client experiences

Adding a private server’s URL to Claude, Cursor, or any other MCP client kicks off a sequence the user mostly sees as one login:

• The client makes an unauthenticated request and gets a 401 carrying a challenge that names the server’s protected-resource metadata.
• The client fetches that metadata, learns the authorization server is the same host, and fetches the authorization server metadata.
• The client identifies itself, either by registering through Dynamic Client Registration (DCR) or by presenting the URL of a Client ID Metadata Document (CIMD).
• The client opens the authorize URL with a PKCE challenge. Because the server is private, the browser is sent to Speakeasy login first.
• After login, the consent screen appears.
• Approving redirects back to the client with an authorization code.
• The client exchanges the code for an access token and a refresh token.
• The client refreshes silently from then on, until the sign-in reaches its Session length.

How clients identify themselves, what the registration endpoint accepts, how redirect URIs are validated, and which clients the Client access setting admits are covered in OAuth client registration.

There are no OAuth scopes here. The authorization server advertises no scopes_supported, the registration request has no scope field, and tokens carry none. Access is decided by roles and per-tool team access rules rather than by scopes. Upstream authorization servers do use real upstream scopes, which is a separate mechanism.

The consent screen

Consent is shown on every authorization, even for a client that has connected before, because the prompt is what guards against one client being confused for another. The one exception is a server behind a shared authorization server, where an approval already given for the same client carries over.

The screen names the client asking for access and the server it wants, shown as “Client is requesting access to the MCP server slug”. When the upstream publishes RFC 9728 protected-resource metadata, the card also shows the resource’s own name and its Documentation, Policy, and Terms links, falling back to the authorization server’s metadata when the resource advertises none.

A summary row reads “Signing in as” with the resolved identity and the chosen session length. Expanding Configuration shows the details behind it:

• Client verified from: the host of the client ID URL, shown for CIMD clients only. The client name comes from the client’s own document, but the host is something the client cannot forge, so it is the part a user can check.
• Will redirect to: where the authorization code is sent.
• Session length: a picker with the server maximum preselected and shorter presets below it. See Session length.
• Auto refresh: whether upstream connections are renewed in the background, shown when the server has upstream services to connect. See What people see on the consent screen.

When a CIMD client receives its authorization at a local address, an extra warning tells the user to approve only if they started the request from an app running on that computer.

When the server has authorization servers attached, a Connect required services list appears below, and Give Access stays disabled until at least one service is connected. See What the end user sees. Services reached through Enterprise Managed Auth show as Connected through your organization and need no connect step.

The screen ends with Give Access and Cancel.

Tool selection on the consent screen

When tool filtering on consent screens is turned on for the organization, people can limit a connection to specific tools when they grant access. They choose by tool annotation (read-only, destructive, idempotent, or open-world) or pick individual tools. An annotation choice can either follow the server as tools are added or stay fixed to the tools that match at approval. The selection applies to both listing and calling tools, survives refreshes, and is replaced when the person authorizes again.

An organization admin turns this on from the MCP Sessions page under Identity. Changing it requires the org:admin scope. See Organization-wide view.

Shared authorization servers

By default, every MCP server is its own authorization server. A client registers with each server separately, and a person approves each one on its own consent screen. When an organization runs many servers, people end up approving the same client over and over.

A shared authorization server serves several MCP servers from one issuer URL. When a person has already approved a client for one server under that issuer, connecting the same client to another of its servers skips the consent screen. The screen still appears when the new server needs something the person hasn’t approved, such as an upstream service to connect. Only the approval is shared: each server still gets its own tokens, its own tool selection, and its own team access rules, and revoking a session works per server as before.

Organization admins can see each authorization server’s mode and issuer URL on the Speakeasy authorization servers page in organization settings. Copy the issuer URL from there when an identity provider such as Okta asks for the authorization server.

Moving an existing MCP server to a different authorization server makes every client connected to it authorize again. The dashboard warns before saving that change, so plan it for a time when re-authorizing won’t interrupt people.

Token lifetimes

Access tokens last one hour, and that value is not configurable. When the sign-in’s Session length deadline is less than an hour away, the access token expires at the deadline instead. Refreshing never extends the sign-in past that deadline, which is fixed when the person approves access. See Session length.

Refresh tokens rotate. Each refresh returns a new refresh token and retires the one presented. When a client sends the same refresh token again within a short grace period, as happens when several open sessions refresh in parallel, it gets the same response. After that, the retired token is rejected. A refresh token is also bound to the client it was issued to, and presenting it from another client revokes it.

Revoking access

Revocation exists at three levels:

• One session, ending a single client’s connection.
• One client registration, rejecting every future token minted for that client ID and ending every session issued through it, including sessions on other servers the same issuer gates.
• One person’s upstream credentials, covered in Upstream credentials.

Revoking takes effect immediately, but a client can authorize again and reconnect. Revoking a session or a client invalidates tokens the platform issued, not the upstream OAuth tokens obtained for the user. Those are never revoked at the upstream service. The stored credential remains encrypted and becomes effectively inaccessible, but the grant can still appear as an active session in the upstream service until it is revoked there directly.

Live connections across the project can be seen and revoked from MCP Sessions under Identity in the project sidebar. The same sessions and client registrations appear per server on its Clients and Sessions tab.