***

title: Session & SessionManager
slug: /reference/python/agents/mcp-gateway/session-manager
description: Manage MCP session lifecycles with automatic timeout and cleanup.
max-toc-depth: 3
---------------------

For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

[mcpclient]: /docs/server-sdks/reference/python/agents/mcp-gateway/mcp-client

[sessionmanager-createsession]: /docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/create-session

[getsession]: /docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/get-session

[createsession]: /docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/create-session

[closesession]: /docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/close-session

[listsessions]: /docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/list-sessions

[shutdown]: /docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/shutdown

The session management layer tracks active MCP sessions tied to SignalWire call
IDs. Each session wraps an [`MCPClient`][mcpclient]
process and is automatically cleaned up when it expires or when the underlying
process dies.

```python
from signalwire.mcp_gateway import Session, SessionManager
```

***

## Session

A dataclass representing a single active MCP session. Sessions are created by
[`SessionManager.create_session()`][sessionmanager-createsession]
and should not be instantiated directly.

### Properties

<ParamField path="session_id" type="str" toc={true}>
  Unique identifier for the session, typically a SignalWire call ID.
</ParamField>

<ParamField path="service_name" type="str" toc={true}>
  Name of the MCP service this session is connected to.
</ParamField>

<ParamField path="process" type="MCPClient" toc={true}>
  The [`MCPClient`][mcpclient] instance
  managing the MCP server process for this session.
</ParamField>

<ParamField path="created_at" type="datetime" toc={true}>
  Timestamp when the session was created.
</ParamField>

<ParamField path="last_accessed" type="datetime" toc={true}>
  Timestamp of the most recent activity on this session. Updated automatically
  when the session is retrieved via
  [`get_session()`][getsession].
</ParamField>

<ParamField path="timeout" type="int" default="300" toc={true}>
  Session timeout in seconds. The session is considered expired when
  `last_accessed + timeout` is in the past.
</ParamField>

<ParamField path="metadata" type="dict[str, Any]" default="{}" toc={true}>
  Arbitrary metadata attached to the session.
</ParamField>

<ParamField path="is_expired" type="bool" toc={true}>
  Read-only property. Returns `True` if the session has exceeded its timeout
  since the last access.
</ParamField>

<ParamField path="is_alive" type="bool" toc={true}>
  Read-only property. Returns `True` if the underlying MCP client process is
  still running.
</ParamField>

### touch

**touch**() -> `None`

Update `last_accessed` to the current time, resetting the expiration clock.
Called automatically by
[`get_session()`][getsession].

***

## SessionManager

Manages the full lifecycle of MCP sessions including creation, retrieval,
cleanup, and resource limits. Runs a background thread that periodically
removes expired or dead sessions.

## **Methods**

<CardGroup cols={2}>
  <Card title="create_session" href="/docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/create-session">
    Create and register a new MCP session.
  </Card>

  <Card title="get_session" href="/docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/get-session">
    Retrieve an active session by ID.
  </Card>

  <Card title="close_session" href="/docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/close-session">
    Close and remove a session.
  </Card>

  <Card title="list_sessions" href="/docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/list-sessions">
    List all active sessions with metadata.
  </Card>

  <Card title="shutdown" href="/docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/shutdown">
    Close all sessions and stop the cleanup thread.
  </Card>
</CardGroup>