MetorialDocs

Sessions

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

The Session object

session.json
{
  "object": "session",
  "id": "ses_4dEfGhJkLmNpQrSt",
  "status": "active",
  "name": "Production Session",
  "description": "Session for production environment",
  "metadata": {},
  "connection_state": "connected",
  "connection_url": "https://mcp.metorial.com/mcp/ses_4dEfGhJkLmNpQrSt",
  "client_secret": "metorial_fk_4eC39HqLyjWDarjtT1zdp7dc",
  "usage": {
    "total_productive_client_message_count": 0,
    "total_productive_provider_message_count": 0
  },
  "providers": [
    {
      "object": "session.provider",
      "id": "spr_3cDeFgHjKlMnPqRs",
      "status": "active",
      "usage": {},
      "tool_filter": {
        "type": "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"
    },
    {
      "object": "session.provider",
      "id": "spr_3cDeFgHjKlMnPqRs",
      "status": "active",
      "usage": {},
      "tool_filter": {
        "type": "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"
    }
  ],
  "from_template_ids": [
    "example_from_template_ids"
  ],
  "has_errors": false,
  "has_warnings": false,
  "identity_actor_id": "example_identity_actor_id",
  "identity_id": "example_identity_id",
  "created_at": "2025-09-15T10:30:00.000Z",
  "updated_at": "2026-01-10T14:45:00.000Z"
}
object"session"required
idstringrequired
status"active" | "archived" | "deleted"required
namestringrequirednullable
descriptionstringrequirednullable
metadataRecord<string, any>requirednullable
connection_state"connected" | "disconnected"required
connection_urlstringrequired
client_secretstringrequirednullable
from_template_idsstring[]required
has_errorsbooleanrequired
has_warningsbooleanrequired
identity_actor_idstringrequirednullable
identity_idstringrequirednullable
created_atdaterequired
updated_atdaterequired

Endpoints

List sessions

GET/sessions

Returns a paginated list of sessions.

Query parameters

status"active" | "archived" or "active" | "archived"[]optional

Filter by status (active, archived)

idstring or string[]optional

Filter by session ID(s)

agent_idstring or string[]optional

Filter by connected agent ID(s)

actor_idstring or string[]optional

Filter by connected identity actor ID(s)

consumer_idstring or string[]optional

Filter by connected consumer ID(s)

identity_idstring or string[]optional

Filter by connected identity ID(s)

session_template_idstring or string[]optional

Filter by session template ID(s)

session_provider_idstring or string[]optional

Filter by session provider ID(s)

provider_idstring or string[]optional

Filter by provider ID(s)

provider_deployment_idstring or string[]optional

Filter by provider deployment ID(s)

provider_config_idstring or string[]optional

Filter by provider config ID(s)

provider_auth_config_idstring or string[]optional

Filter by provider auth config ID(s)

Example request

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

Get session

GET/sessions/:session_id

Retrieves a specific session by ID.

Path parameters

session_idstringrequired

The unique identifier for the session

Example request

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

Create session

POST/sessions

Creates a new session with provider deployments.

Request body

namestringoptional
descriptionstringoptional
metadataRecord<string, any>optional

Example request

curl -X POST "https://api.metorial.com/sessions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "example_name",
  "description": "example_description",
  "metadata": {},
  "providers": [
    {
      "provider_deployment": "example_provider_deployment_id",
      "provider_config": "example_provider_config_id",
      "provider_auth_config": "example_provider_auth_config_id",
      "session_template_id": "example_session_template_id",
      "tool_filters": {
        "type": "tool_keys",
        "keys": [
          "example_keys"
        ]
      }
    }
  ]
}'

Update session

PATCH/sessions/:session_id

Updates a session.

Path parameters

session_idstringrequired

The unique identifier for the session

Request body

namestringoptional
descriptionstringoptional
metadataRecord<string, any>optional

Custom key-value pairs for storing additional information

Example request

curl -X PATCH "https://api.metorial.com/sessions/ses_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer metorial_sk_io2h4..." \
  -d '{
  "name": "My updated session",
  "description": "Updated session description",
  "metadata": {}
}'

Delete session

DELETE/sessions/:session_id

Deletes a session.

Path parameters

session_idstringrequired

The unique identifier for the session

Example request

curl -X DELETE "https://api.metorial.com/sessions/ses_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_io2h4..."