# Sessions
URL: https://metorial.com/docs/build/operate/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.

---

<PageIntro>
  <Learn>
    * What sessions are and how they work
    * Attaching multiple providers to a session
    * Tool filters
    * Connections, messages, and events
    * Session templates
  </Learn>

  <Reading title="References">
    * [Providers guide](/docs/platform/operate/providers)
    * [OAuth integrations](/docs/platform/integrations/oauth)
  </Reading>
</PageIntro>

## What is a session? [#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 [#attaching-providers]

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

```json
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.

<Callout type="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.
</Callout>

## Tool filters [#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 [#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 [#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]

**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
POST /session-templates
{
  "name": "Research agent",
  "providers": [
    { "provider_deployment_id": "pdp_exa" },
    { "provider_deployment_id": "pdp_brave" }
  ]
}
```