HTTP Session Initialization (Preview)

When calling the OAC MCP server over HTTP directly, the endpoint may require an MCP session before it accepts tools/call requests.

If you call a tool before initializing the session, the server can return an error like:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Unknown error",
    "data": "Mcp-Session-Id header required for tools/call"
  },
  "id": 10
}

Note:

Future MCP protocols may not use the MCP-Session-ID.

Use this sequence

1. Send initialize to the MCP endpoint.
2. Capture the Mcp-Session-Id response header.
3. Send notifications/initialized with that same session ID.
4. Send all later tools/call requests with Mcp-Session-Id: <session-id>.

Initialize the session

curl -i --location 'https://<oac-instance>.analytics.ocp.oraclecloud.com/api/mcp' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'Authorization: Bearer <token>' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {
        "name": "curl-test",
        "version": "1.0"
      }
    }
  }'

Look for the session header in the response

Mcp-Session-Id: <session-id>

Notify the server that initialization is complete

curl --location 'https://<oac-instance>.analytics.ocp.oraclecloud.com/api/mcp' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'Authorization: Bearer <token>' \
  --header 'Mcp-Session-Id: <session-id>' \
  --data '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized"
  }'

Then call tools using the same session ID

curl --location 'https://<oac-instance>.analytics.ocp.oraclecloud.com/api/mcp' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'Authorization: Bearer <token>' \
  --header 'Mcp-Session-Id: <session-id>' \
  --data '{
    "jsonrpc": "2.0",
    "id": 10,
    "method": "tools/call",
    "params": {
      "name": "oracle_analytics-search_catalog",
      "arguments": {
        "types": ["subjectAreas"],
        "limit": 20,
        "sortBy": "name",
        "sortOrder": "ASC"
      }
    }
  }'

The Mcp-Session-Id is session state for the MCP HTTP transport. It is separate from the bearer token. The bearer token authenticates the request; the MCP session ID binds later JSON-RPC messages to the initialized MCP session. Reuse the same session ID for all requests in that MCP session.