Sessions

Sessions are the runtime layer that connects your application to one or more providers. Each session gives your AI access to tools from all the providers attached to it.

What you’ll learn:

• What sessions are and how they work
• Attaching multiple providers to a session
• Tool filters
• Connections, messages, and events
• Session templates

References:

• Providers Guide
• OAuth Integrations

What is a Session?

A session is a runtime context that connects your AI application to one or more providers. When you create a session, Metorial:

1. Resolves each attached provider deployment and its config/auth
2. Returns a connection_url you can connect an MCP client to
3. Exposes the combined tools from all attached providers

Sessions are designed to be created per-request or per-user interaction—they’re lightweight and fast to start.

Attaching Providers

When creating a session, you pass a providers array. Each entry specifies a provider deployment and an optional tool filter:

POST /sessions
{
  "providers": [
    {
      "provider_deployment_id": "pdp_abc123"
    },
    {
      "provider_deployment_id": "pdp_def456",
      "tool_filters": {
        "type": "allow",
        "keys": ["send_message", "list_channels"]
      }
    }
  ]
}

You can attach multiple providers—from the same provider or different ones—in a single session. The tools from all of them are merged and exposed to your AI.

Auth configs and provider configs are resolved automatically from your project. If a provider deployment requires auth and you have an auth config for it, Metorial uses it. You can also specify which auth config to use explicitly.

Tool Filters

Tool filters let you control which tools from a provider are available during a session. This is useful for:

• Restricting a session to only the tools your AI actually needs
• Preventing destructive actions (e.g. allowing read-only tools only)
• Building scoped agents with minimal permissions

Filters are set per-provider within a session, so you can give different providers different access levels in the same session.

Connections

A connection is created automatically the first time something communicates through a session—either when an MCP client connects or when a tool call is sent via the API.

A single session can have multiple connections (e.g. multiple MCP clients, or a mix of MCP and direct tool calls). Each connection is tracked independently.

Connections support four transport types:

Transport	Description
mcp	Standard MCP protocol client connection
tool_call	Direct tool call via the Metorial API
metorial_protocol	Internal Metorial protocol
system	System-generated connections

Messages and Events

Within a session you can inspect:

• Messages: Individual tool calls and MCP protocol messages exchanged during the session. Each message has an input, output, status, and timing information.
• Events: Significant occurrences like connections opening, errors, or state changes. Useful for monitoring and debugging.
• Participants: The clients and providers involved in the session (e.g. your application, specific provider instances).

These are all read-only resources you access via the API for monitoring and debugging.

Session Templates

Session templates let you save a provider configuration so you can create identical sessions quickly without repeating the setup each time. A template stores the providers list (with tool filters) and can be reused across your application.

POST /session-templates
{
  "name": "Research agent",
  "providers": [
    { "provider_deployment_id": "pdp_exa" },
    { "provider_deployment_id": "pdp_brave" }
  ]
}

What’s Next?

Providers Guide

Understand provider deployments, configs, and auth configs.

OAuth Integrations

Set up OAuth so your users can authorize providers.

Monitoring

View session logs, messages, and events.

Provider Examples

Use sessions with OpenAI, Anthropic, Google, and more.