# MCP sessions

An MCP session is the OAuth connection the platform brokers between an MCP client and an MCP server. Each session belongs to a subject, usually a person, and can also belong to an agent, an API key, an anonymous client, or a workload. The **MCP Sessions** page shows who holds a connection, which upstream services it reaches, and when it was last used, and it is where connections are cut off. Open it from **Identity > MCP Sessions** in the project sidebar.

Each MCP server and gateway also lists its own sessions on its **Clients and Sessions** tab. See [MCP servers](/docs/ai-control-plane/mcp-gateway/access/clients-and-sessions) and [Gateways](/docs/ai-control-plane/mcp-gateway/gateway-endpoints#clients-and-sessions).

> The MCP Sessions page is in preview and enabled per organization.

## Access requirements

> Viewing the page requires the `project:read` scope, which both default roles hold. Revoking a connection, a registration, or every connection an agent holds requires `project:write`, which only the [Admin role](/docs/ai-control-plane/org-admin/roles-and-permissions) includes by default. The two organization policies on this page require `org:admin`.

## How sessions are organized

The page shows connections for the current project. Group them by **Identity** to see what each person holds, by **Provider** to see which upstream services are reachable, or by **Agent** to see which clients connect and on whose behalf. Expanding a row shows the other side: a person's clients, or a client's people.

Each connection has a status:

| Status | Meaning |
| --- | --- |
| **Live**, **Idle**, **Expiring** | The connection is usable. |
| **Needs re-auth** | The connection expired and the client must authorize again. |
| **Revoked** | The connection was revoked. |

Connections unused for more than a week, or no longer usable, move to an **Inactive** section. They stay listed because they may still hold credentials worth revoking.

To narrow the list, filter by status, MCP server, or user, or search by subject or client name. Links from an [identity page](/docs/ai-control-plane/identity/identities) open the list already filtered to that person.

## Revoke access

Three actions end access, each from a row menu:

- **Revoke connection** ends one session.
- **Revoke all connections** ends every session a client holds.
- **Revoke registration** rejects every future token for that client ID and ends every session issued through it, including sessions on other servers that use the same issuer.

Revoking takes effect immediately, but a client can authorize again and reconnect. To stop a person from calling tools without ending their sessions, use a [killswitch](/docs/ai-control-plane/identity/identities#killswitches) instead. The row menus link to one with the **MCP tool calls** capability preselected. Revoking a session never creates or lifts a killswitch.

Revoking a connection invalidates the token the platform issued to the client, not upstream OAuth tokens held for the user, as described in [Revoking access](/docs/ai-control-plane/mcp-gateway/access/user-sessions#revoking-access).

## Control session refresh

The **Automatic session refresh policy** at the top of the page decides, for the whole organization, whether upstream connections are refreshed in the background before they expire. Choose **Disabled** to let inactive connections expire, **User controlled** to let each person choose on the consent screen, or **Required** to refresh every eligible connection. See [Session length and refresh](/docs/ai-control-plane/mcp-gateway/access/session-refresh) for what each option does and how refresh interacts with session length and revocation.

## Let users choose tools on consent screens

When tool filtering on consent screens is turned on, users can limit a connection to specific tools when they grant access. They can 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 user authorizes again.

For how sessions are established and how long tokens last, see [User sessions](/docs/ai-control-plane/mcp-gateway/access/user-sessions). For how long a sign-in lasts, see [Session length](/docs/ai-control-plane/mcp-gateway/access/session-refresh#session-length).