Sessions

Sessions are connections to providers that allow clients to interact with MCP servers. Each session can include one or more provider deployments.

Sessions object

Attributes

object

String

String representing the object's type

id

String

Unique session identifier

name

StringNullable

Display name

description

StringNullable

Description

metadata

ObjectNullable

Custom key-value pairs for storing additional information

connection_state

String

Session connection state

connection_url

String

MCP connection URL for this session

usage

Object

providers

Object

Session providers

from_templates_ids

Array of Strings

Template IDs this session was created from

has_errors

Boolean

Whether the session has any errors

has_warnings

Boolean

Whether the session has any warnings

created_at

Date

Timestamp when created

updated_at

Date

Timestamp when last updated

{
  "object": "session",
  "id": "ses_4dEfGhJkLmNpQrSt",
  "name": "Production Session",
  "description": "Session for production environment",
  "metadata": {
    "imported_from": "legacy-system",
    "migration_date": "2025-09-01"
  },
  "connection_state": "connected",
  "connection_url": "https://mcp.metorial.com/mcp/ses_4dEfGhJkLmNpQrSt",
  "usage": {},
  "providers": [
    {
      "object": "session.provider",
      "id": "spr_3cDeFgHjKlMnPqRs",
      "status": "active",
      "usage": {},
      "tool_filter": {
        "type": "v1.allow_all"
      },
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "session_id": "ses_4dEfGhJkLmNpQrSt",
      "from_template_id": "stm_2bCdEfGhJkLmNpQr",
      "from_template_provider_id": "stp_3cDeFgHjKlMnPqRs",
      "deployment": {
        "object": "provider.deployment#preview",
        "id": "pde_1aBcDeFgHjKlMnPq",
        "name": "Production",
        "description": "Production deployment",
        "metadata": {},
        "provider_id": "pro_5gHjKlMnPqRsTuVw",
        "created_at": "2025-09-15T10:30:00.000Z",
        "updated_at": "2026-01-10T14:45:00.000Z"
      },
      "config": {
        "object": "provider.config#preview",
        "id": "pcf_7dEfGhJkLmNpQrSt",
        "name": "Production Config",
        "description": "Configuration for production environment",
        "metadata": {},
        "provider_id": "pro_5gHjKlMnPqRsTuVw",
        "created_at": "2025-09-15T10:30:00.000Z",
        "updated_at": "2026-01-10T14:45:00.000Z"
      },
      "auth_config": {
        "object": "provider.auth_config#preview"
      },
      "created_at": "2025-09-15T10:30:00.000Z",
      "updated_at": "2026-01-10T14:45:00.000Z"
    }
  ],
  "created_at": "2025-09-15T10:30:00.000Z",
  "updated_at": "2026-01-10T14:45:00.000Z"
}

List sessions

Returns a paginated list of sessions.

Query Parameters

limit

NumberOptional

Maximum number of items to return (1-100)

after

StringOptional

Return items after this ID

before

StringOptional

Return items before this ID

cursor

StringOptional

Pagination cursor from a previous response

order

EnumOptional

Sort order for results

status

UnionOptional

Filter by status (active, archived)

id

UnionOptional

Filter by session ID(s)

session_template_id

UnionOptional

Filter by session template ID(s)

session_provider_id

UnionOptional

Filter by session provider ID(s)

provider_id

UnionOptional

Filter by provider ID(s)

provider_deployment_id

UnionOptional

Filter by provider deployment ID(s)

provider_config_id

UnionOptional

Filter by provider config ID(s)

provider_auth_config_id

UnionOptional

Filter by provider auth config ID(s)

GEThttp://api.metorial.com/sessions
curl -X GET "https://api.metorial.com/sessions" \
  -H "Authorization: Bearer metorial_sk_..."

Get session

Retrieves a specific session by ID.

URL Parameters

session_id

String

The unique identifier for the session

GEThttp://api.metorial.com/sessions/:session_id
curl -X GET "https://api.metorial.com/sessions/ses_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_..."

Create session

Creates a new session with provider deployments.

Request Body

name

StringOptional

description

StringOptional

metadata

ObjectOptional

A key-value map

providers

Array of Intersection
POSThttp://api.metorial.com/sessions
curl -X POST "https://api.metorial.com/sessions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "metadata": {},
  "providers": [
    {
      "provider_deployment_id": "example_provider_deployment_id",
      "tool_filters": {
        "type": "example_type",
        "keys": [
          "example_item"
        ]
      }
    }
  ]
}'

Update session

Updates a session.

URL Parameters

session_id

String

The unique identifier for the session

Request Body

name

StringOptional

description

StringOptional

metadata

ObjectOptional

Custom key-value pairs for storing additional information

PATCHhttp://api.metorial.com/sessions/:session_id
curl -X PATCH "https://api.metorial.com/sessions/ses_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "metadata": {}
}'