> ## Documentation Index
> Fetch the complete documentation index at: https://metorial.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  **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](/concepts-providers)
  * [OAuth Integrations](/integrations-oauth)
</Note>

## 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**:

```json theme={null}
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.

<Info>
  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.
</Info>

## 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.

```json theme={null}
POST /session-templates
{
  "name": "Research agent",
  "providers": [
    { "provider_deployment_id": "pdp_exa" },
    { "provider_deployment_id": "pdp_brave" }
  ]
}
```

## What's Next?

<CardGroup cols={2}>
  <Card title="Providers Guide" icon="server" href="/concepts-providers">
    Understand provider deployments, configs, and auth configs.
  </Card>

  <Card title="OAuth Integrations" icon="shield" href="/integrations-oauth">
    Set up OAuth so your users can authorize providers.
  </Card>

  <Card title="Monitoring" icon="chart-line" href="/concepts-monitoring">
    View session logs, messages, and events.
  </Card>

  <Card title="Provider Examples" icon="code" href="/sdk-providers-overview">
    Use sessions with OpenAI, Anthropic, Google, and more.
  </Card>
</CardGroup>