***

title: create_session
slug: /reference/python/agents/mcp-gateway/session-manager/create-session
description: Create and register a new MCP session.
max-toc-depth: 3
---------------------

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

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

Create and register a new session. If a session with the same ID already exists,
the old session is closed first. Raises `RuntimeError` if the total session limit
or the per-service session limit is exceeded.

## **Parameters**

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

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

<ParamField path="process" type="MCPClient" required={true} toc={true}>
  The MCP client process to associate with this session.
</ParamField>

<ParamField path="timeout" type="Optional[int]" toc={true}>
  Session timeout in seconds. Defaults to the manager's `default_timeout` (300).
</ParamField>

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

## **Returns**

[`Session`][session] -- The newly created session object.

## **Example**

```python {11}
from signalwire.mcp_gateway import SessionManager, MCPManager

config = {
    "session": {"default_timeout": 300, "max_sessions_per_service": 100},
    "services": {"todo": {"command": ["python3", "todo_mcp.py"], "description": "Todo", "enabled": True}}
}

manager = SessionManager(config)
mcp = MCPManager(config)
client = mcp.create_client("todo")
session = manager.create_session(
    session_id="call-abc-123",
    service_name="todo",
    process=client,
    timeout=600,
    metadata={"caller": "+15551234567"}
)
print(session.session_id)  # "call-abc-123"
```