> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# Session & SessionManager

> Manage MCP session lifecycles with automatic timeout and cleanup.

[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

**`session_id`** `str`

Unique identifier for the session, typically a SignalWire call ID.

---

**`service_name`** `str`

Name of the MCP service this session is connected to.

---

**`process`** `MCPClient`

The [`MCPClient`][mcpclient] instance
managing the MCP server process for this session.

---

**`created_at`** `datetime`

Timestamp when the session was created.

---

**`last_accessed`** `datetime`

Timestamp of the most recent activity on this session. Updated automatically
when the session is retrieved via
[`get_session()`][getsession].

---

**`timeout`** `int` — default: 300

Session timeout in seconds. The session is considered expired when
`last_accessed + timeout` is in the past.

---

**`metadata`** `dict[str, Any]` — default: \{}

Arbitrary metadata attached to the session.

---

**`is_expired`** `bool`

Read-only property. Returns `True` if the session has exceeded its timeout
since the last access.

---

**`is_alive`** `bool`

Read-only property. Returns `True` if the underlying MCP client process is
still running.

---

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

#### [create\_session](/docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/create-session)

Create and register a new MCP session.

#### [get\_session](/docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/get-session)

Retrieve an active session by ID.

#### [close\_session](/docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/close-session)

Close and remove a session.

#### [list\_sessions](/docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/list-sessions)

List all active sessions with metadata.

#### [shutdown](/docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/shutdown)

Close all sessions and stop the cleanup thread.

> Manage MCP session lifecycles with automatic timeout and cleanup.

## Docs

- [close_session](https://signalwire.com/docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/close-session.md): Close and remove a session.
- [create_session](https://signalwire.com/docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/create-session.md): Create and register a new MCP session.
- [get_session](https://signalwire.com/docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/get-session.md): Retrieve an active session by ID.
- [list_sessions](https://signalwire.com/docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/list-sessions.md): List all active sessions with their metadata.
- [shutdown](https://signalwire.com/docs/server-sdks/reference/python/agents/mcp-gateway/session-manager/shutdown.md): Close all sessions and stop the background cleanup thread.