---
title: "List MCP sessions"
method: GET
path: "/api/mcp/sessions"
tags: ["MCP"]
---

# List MCP sessions

`GET /api/mcp/sessions`

Returns every per-user MCP authentication artifact visible to the caller —
OAuth tokens, header credentials, and pending submission / consent flows.

Row visibility is scoped to the caller's identity (Virtual Key, signed-in
user, or asserted session ID). Server-level `headers` / `oauth` clients
are not surfaced here; their credentials live on the MCP client config.

When both a credential and a pending flow exist for the same
`(identity, mcp_client)` binding, the credential is returned and the
flow is suppressed to avoid duplicate entries.

## Response `200`

Sessions visible to the caller

- MCPSessionsListResponse
  - `sessions` MCPSessionRow[], required
    - `id` string, required — Row primary key — token UUID, header credential UUID, or flow UUID
    - `kind` 'token' | 'header' | 'flow', required — Row type: - token: completed per-user OAuth credential - header: completed per-user-headers credential - flow: pending submission / consent flow (use auth_kind to disambiguate OAuth vs Headers)
    - `auth_kind` 'oauth' | 'headers', required — Disambiguates flow rows by which auth surface they belong to. For `kind=token` this is always `oauth`; for `kind=header` always `headers`.
    - `auth_mode` 'user' | 'vk' | 'session', required — Identity dimension this credential is keyed against
    - `user_id` string, nullable — Populated on user-keyed rows; refers to the SCIM user table
    - `user` MCPUserSummary — Minimal user view embedded on user-keyed session rows.
      - `id` string
      - `name` string
    - `virtual_key` MCPVirtualKeySummary — Minimal virtual-key view embedded in session rows.
      - `id` string
      - `name` string
    - `mcp_client` MCPClientSummary — Minimal MCP client view embedded in session rows.
      - `client_id` string
      - `name` string
    - `session_id` string, nullable — Populated only on session-keyed rows
    - `status` 'active' | 'orphaned' | 'pending' | 'needs_reauth' | 'needs_update', required — OAuth tokens use: active | orphaned | needs_reauth. Header credentials use: active | orphaned | needs_update. Flow rows use: pending.
    - `expires_at` string, date-time, nullable — When the OAuth access token expires; nil for header rows
    - `created_at` string, date-time, required
    - `last_refreshed_at` string, date-time, nullable — OAuth token rows only — last successful refresh
    - `updated_at` string, date-time, nullable — Header credential rows only — last submission / edit
    - `oauth_config_id` string, nullable — OAuth rows only
    - `can_reauth` boolean, required — Mirrors the server-side identity gate on POST /api/mcp/sessions/{id}/reauth. Always true for vk- and session-mode rows. For user-mode rows, true only when the calling user matches the row's bound user — admin DAC scope is enough to see the row, but reauthing mints credentials under whoever clicks the URL, so the server returns 403 to non-bound callers. The UI hides the Re-authenticate / Edit values action when this is false.

## Other responses

- `401` — Unauthorized — missing or invalid credentials
- `500` — Internal server error

---

[API](https://skmtc.net/getbifrost/apis/bifrost-api.md) · [All operations](https://skmtc.net/getbifrost/apis/bifrost-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getbifrost/bifrost-api/revisions/f8cab88f64ea/schema)