Session Lifecycle

​

Session Initialization

Our MCP server uses a two-step initialization process over HTTP:

1. Initialize Request: Client sends initialize method with protocol version and capabilities
2. Initialized Notification: Client confirms readiness with notifications/initialized

​

Initialize Request

The client initiates a session by sending an initialize request:

{
  "jsonrpc": "2.0",
  "id": "init-123",
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "roots": {
        "listChanged": true
      },
      "sampling": {}
    },
    "clientInfo": {
      "name": "ExampleClient",
      "version": "1.0.0"
    }
  }
}

​

Initialize Response

The server responds with its capabilities and information:

{
  "jsonrpc": "2.0",
  "id": "init-123",
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": {
        "listChanged": true
      },
      "resources": {
        "subscribe": true,
        "listChanged": true
      },
      "prompts": {
        "listChanged": true
      },
      "completions": {}
    },
    "serverInfo": {
      "name": "Kambrium MCP Server",
      "version": "1.0.0"
    }
  }
}

The server includes a Mcp-Session-Id header in the response for session tracking.

​

Initialized Notification

After receiving the initialize response, the client MUST send an initialized notification:

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

This notification MUST include the Mcp-Session-Id header from the initialize response.

​

Lifecycle Rules

• The client SHOULD NOT send requests other than pings before the server responds to initialize
• The server SHOULD NOT send requests other than pings before receiving notifications/initialized
• All subsequent requests MUST include the Mcp-Session-Id header

​

Version Negotiation

The client MUST send a protocol version in the initialize request. Our server supports:

• "2025-03-26" (current)
• "2024-11-05" (legacy support)

If the server supports the requested version, it responds with the same version. Otherwise, it responds with its preferred supported version.

If the client doesn’t support the server’s response version, it SHOULD disconnect.

​

Capability Negotiation

Client and server capabilities establish which protocol features are available during the session.

Our Server Capabilities:

Client Capabilities (optional):

• roots: Directory roots with change notifications
• sampling: LLM sampling configuration

​

Session Management

​

Session State

Each session maintains:

• Session ID: Unique identifier for the session
• Protocol Version: Negotiated MCP protocol version
• Initialization Status: Whether notifications/initialized was received
• Request ID Tracking: Ensures request ID uniqueness within the session
• Client Information: Name and version from initialize request

​

Session Termination

Sessions can be terminated by:

1. Client Disconnect: HTTP connection closes
2. Server Shutdown: Graceful server shutdown
3. Timeout: Session inactivity timeout (configurable)
4. Error: Unrecoverable protocol errors

​

Error Handling

Initialization Errors:

{
  "jsonrpc": "2.0",
  "id": "init-123",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "error": "Unsupported protocol version: 2023-01-01",
      "supported_versions": ["2025-03-26", "2024-11-05"]
    }
  }
}

Common Error Codes:

• -32600: Invalid Request (malformed initialize request)
• -32602: Invalid params (missing protocolVersion, unsupported version)
• -32603: Internal error (server initialization failure)

​

Implementation Notes

​

HTTP Transport Specifics

• Session Headers: Mcp-Session-Id header required after initialization
• Request ID Uniqueness: Enforced per session, not globally
• Batch Requests: Supported as per JSON-RPC 2.0 specification
• Notifications: Return HTTP 202 (Accepted) status code

​

Session Lifecycle Example

# 1. Initialize session
curl -X POST "https://api.kambrium.com/pipedrive/mcp" \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "init-1",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "test-client", "version": "1.0.0"}
    }
  }'

# Response includes: Mcp-Session-Id: abc123

# 2. Send initialized notification
curl -X POST "https://api.kambrium.com/pipedrive/mcp" \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: abc123" \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized"
  }'

# 3. Use MCP methods with session ID
curl -X POST "https://api.kambrium.com/pipedrive/mcp" \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: abc123" \
  -d '{
    "jsonrpc": "2.0",
    "id": "tools-1",
    "method": "tools/list"
  }'