---
title: "Mcp Agent Session Start"
method: POST
path: "/v1/mcp/projects/{project_id}/agent/sessions"
tags: ["mcp"]
---

# Mcp Agent Session Start

`POST /v1/mcp/projects/{project_id}/agent/sessions`

## Request

- Base URL: `https://api.sonenta.dev`
- URL: `https://api.sonenta.dev/v1/mcp/projects/{project_id}/agent/sessions`
- Auth: none declared

Open an observability session. Send `X-MCP-Session-Id: <session_id>` on
every subsequent MCP call so backend auto-capture attaches mutations to this
thread. Idempotent on a running (project, session_ref).

## Path parameters

- `project_id` string, required

## Request body

- AgentSessionStartIn
  - `agent` string, required: Stable agent label shown in the dashboard
  - `title` string, nullable
  - `session_ref` string, nullable: Client idempotency key; defaults to the X-MCP-Session-Id header
  - `metadata` object, nullable
  - `agent_type` string, nullable
  - `agent_version` string, nullable

## Response `200`

Successful Response

- AgentSessionStartOut
  - `v` integer
  - `session_id` string, required
  - `status` string, required
  - `started_at` string, date-time, required
  - `session_header` string
  - `channel` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/sonenta/apis/sonenta-api.md) · [All operations](https://skmtc.dev/sonenta/apis/sonenta-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sonenta/apis/sonenta-api/revisions/f853ea49fb05?raw)