MetorialDocs

Session Connections

Session connections represent the MCP connections established within a session. This read-only resource provides visibility into the connection state and capabilities.

The Session Connection object

session_connection.json
{
  "object": "session.connection",
  "id": "scn_8hJkLmNpQrStUvWx",
  "connection_state": "connected",
  "transport": "mcp",
  "usage": {
    "total_productive_client_message_count": 0,
    "total_productive_provider_message_count": 0
  },
  "mcp": {
    "capabilities": {},
    "protocol_version": "2024-11-05",
    "transport": "none"
  },
  "session_id": "ses_4dEfGhJkLmNpQrSt",
  "participant": {
    "object": "session.participant",
    "id": "spt_5eFgHjKlMnPqRsTu",
    "type": "unknown",
    "identifier": "claude-desktop",
    "name": "Claude Desktop",
    "data": {
      "identifier": "claude-desktop",
      "name": "Claude Desktop"
    },
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "connection_type": "mcp",
    "agent_id": "example_agent_id",
    "agent_instance_id": "example_agent_instance_id",
    "identity_actor_id": "example_identity_actor_id",
    "identity_id": "example_identity_id",
    "agent_actor_id": "example_agent_actor_id",
    "agent_client_id": "example_agent_client_id",
    "consumer_id": "example_consumer_id",
    "created_at": "2025-09-15T10:30:00.000Z"
  },
  "has_errors": false,
  "has_warnings": false,
  "created_at": "2025-09-15T10:30:00.000Z",
  "last_message_at": "2025-09-15T10:30:00.000Z",
  "last_active_at": "2025-09-15T10:30:00.000Z"
}
object"session.connection"required
idstringrequired
connection_state"connected" | "disconnected"required
transport"mcp" | "tool_call" | "metorial_protocol" | "system"required
session_idstringrequired
has_errorsbooleanrequired
has_warningsbooleanrequired
created_atdaterequired
last_message_atdaterequired
last_active_atdaterequirednullable

Endpoints

List session connections

GET/session-connections

Returns a paginated list of connections for a session.

Query parameters

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

Filter by connection status

connection_state"connected" | "disconnected" or "connected" | "disconnected"[]optional

Filter by connection state

idstring or string[]optional

Filter by session connection 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)

agent_instance_idstring or string[]optional

Filter by connected agent instance ID(s)

session_idstring or string[]optional

Filter by session ID(s)

session_provider_idstring or string[]optional

Filter by session provider ID(s)

participant_idstring or string[]optional

Filter by participant ID(s)

Example request

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

Get session connection

GET/session-connections/:session_connection_id

Retrieves a specific connection from a session.

Path parameters

session_connection_idstringrequired

The unique identifier for the session_connection

Example request

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