Sessions

MCP session lifecycle, headers, and management.

4 min readUpdated 2026-09-07

MCP sessions track your connection state between requests. This page covers session lifecycle and the headers your client needs to include.

Session lifecycle

1. Initialize     →  Session created, ID returned2. Tool calls     →  Session ID required on each request3. Idle timeout   →  Session expires after 60 minutes4. Re-initialize  →  New session created

Sessions are bound to the access token used to create them. When that access token expires, initialize a new session after refreshing the token. When your token is revoked, your session ends.

Initialize

Start a session with the initialize method:

curl -X POST https://mcp.doow.co/mcp \-H "Authorization: Bearer ACCESS_TOKEN_JWT" \-H "Content-Type: application/json" \-H "Accept: application/json, text/event-stream" \-d '{  "jsonrpc": "2.0",  "method": "initialize",  "params": {    "protocolVersion": "2025-03-26",    "capabilities": {},    "clientInfo": { "name": "my-client", "version": "1.0.0" }  },  "id": 1}'

Response headers include your session ID:

Mcp-Session-Id: a3340a5a-e237-4123-8c6c-64c791c150faX-Doow-MCP-Version: 2026-08-29

Required headers

Every request after initialize must include these headers:

Header	Value	Required
`Authorization`	`Bearer ACCESS_TOKEN_JWT`	Yes
`Content-Type`	`application/json`	Yes
`Accept`	`application/json, text/event-stream`	Yes
`Mcp-Session-Id`	Session ID from initialize	Yes (after initialize)

Tool calls

Call tools with the tools/call method:

curl -X POST https://mcp.doow.co/mcp \-H "Authorization: Bearer ACCESS_TOKEN_JWT" \-H "Content-Type: application/json" \-H "Accept: application/json, text/event-stream" \-H "Mcp-Session-Id: a3340a5a-e237-4123-8c6c-64c791c150fa" \-d '{  "jsonrpc": "2.0",  "method": "tools/call",  "params": {    "name": "doow_apps_list",    "arguments": {}  },  "id": 2}'

List available tools

Get the tool catalog with tools/list:

curl -X POST https://mcp.doow.co/mcp \-H "Authorization: Bearer ACCESS_TOKEN_JWT" \-H "Content-Type: application/json" \-H "Accept: application/json, text/event-stream" \-H "Mcp-Session-Id: a3340a5a-e237-4123-8c6c-64c791c150fa" \-d '{  "jsonrpc": "2.0",  "method": "tools/list",  "params": {},  "id": 3}'

The response includes all tools you have access to, based on your MCP scope and Doow role.

Session expiry

Sessions expire after 60 minutes of inactivity. When a session expires, requests return HTTP 404 with a Doow error body:

{"error": {  "code": "SESSION_NOT_FOUND",  "message": "Session expired or invalid",  "details": null,  "action": "Initialize a new MCP session"}}

Re-initialize to create a new session:

curl -X POST https://mcp.doow.co/mcp \-H "Authorization: Bearer ACCESS_TOKEN_JWT" \-H "Content-Type: application/json" \-H "Accept: application/json, text/event-stream" \-d '{"jsonrpc":"2.0","method":"initialize",...}'

SSE streaming

Long-running operations use Server-Sent Events (SSE). Your client receives events as the operation progresses:

event: messagedata: {"jsonrpc":"2.0","id":5,"result":{"content":[...]}}event: messagedata: {"jsonrpc":"2.0","method":"elicitation/create","params":{...}}

The server sends heartbeat comments every 25 seconds to keep the connection alive:

: heartbeat

Elicitation

Protected operations trigger elicitation, which is a server-initiated request for confirmation:

{"jsonrpc": "2.0","id": 7,"method": "elicitation/create","params": {  "mode": "form",  "message": "Confirm freezing card 'Corporate Travel'?",  "requestedSchema": {    "type": "object",    "properties": {      "confirm": { "type": "boolean" }    }  }}}

Your client must respond with the user's decision:

{"jsonrpc": "2.0","id": 7,"result": {  "action": "accept",  "content": {    "confirm": true  }}}

The response uses the request's id. Use action: "decline" or action: "cancel" when the user does not approve. Non-interactive clients that cannot handle elicitation receive an error on protected operations. A plain curl request cannot complete this exchange because the server-initiated request is sent through the active MCP connection.

Close a session

Clients can close a session when they are done:

curl -X DELETE https://mcp.doow.co/mcp \-H "Authorization: Bearer ACCESS_TOKEN_JWT" \-H "Mcp-Session-Id: a3340a5a-e237-4123-8c6c-64c791c150fa"

Doow returns 204 No Content.

Retries and idempotency

For confirmation-gated calls, the server uses the MCP session, member, organization, and JSON-RPC request ID to identify a request. If a response is lost, retry with the same JSON-RPC request ID. A new ID can run the operation again. Reusing an ID while the first call is still running returns an idempotency conflict.

List tools do not all paginate the same way. Check the individual tool schema: many accept limit, while only some expose an offset or cursor. Do not assume every list response has a cursor.

Response headers

Every response includes:

Header	Description
`X-Doow-MCP-Version`	Server implementation version
`X-Request-Id`	Unique request ID for debugging

Rate-limited responses include:

Header	Description
`Retry-After`	Seconds to wait before retrying
`X-RateLimit-Remaining`	Requests remaining in window

Next steps

Scopes

What each scope grants access to.

Troubleshooting

Troubleshoot common errors.

Was this page helpful?