ODE MCP — AUTH FLOW

sequenceDiagram
    autonumber
    participant CC as MCP Client
(Claude Code)
    participant MCP as MCP Server
(ode-mcp-server :8081)
    participant ODE as ODE Core API
(instance-sdk-vX-X-X/v3)

    rect rgb(15, 26, 46)
        Note over MCP,ODE: ① STARTUP — MCP server authenticates itself to ODE core
        MCP->>ODE: POST /v3/user/login
name = API_USERNAME, pwd = API_PASSWORD
        ODE-->>MCP: 200 · sessionID = effff5d4-… · models = [NW]
        Note right of MCP: apiSessionToken = sessionID
(in-memory)
    end

    rect rgb(10, 40, 28)
        Note over CC,MCP: ② MCP SESSION — client establishes an MCP session
        CC->>MCP: POST /mcp (initialize)
Authorization: Bearer MCP_AUTH_TOKEN
        MCP-->>CC: 200 + mcp-session-id: 798ca045-…
        CC->>MCP: POST /mcp (notifications/initialized)
mcp-session-id: 798ca045-…
        MCP-->>CC: 202 Accepted
    end

    rect rgb(50, 32, 12)
        Note over CC,ODE: ③ TOOL CALL — two hops, two different tokens
        CC->>MCP: POST /mcp tools/call ode_request_records value=10248
Bearer MCP_AUTH_TOKEN + mcp-session-id
        MCP->>ODE: GET /v3/nexus/NW/item/10248/nexuses
Authorization Bearer apiSessionToken
        ODE-->>MCP: 200 · nexusGroups → nexuses → tk = NexusKey(0.1.70.599, …)
        MCP->>ODE: GET /v3/nexus/NW/nexus/0.1.70.599/records
Bearer apiSessionToken
        ODE-->>MCP: 200 · records → contextValue = orderID, itemValue = 10248, …
        MCP-->>CC: JSON-RPC result with decoded records
    end

    rect rgb(52, 18, 22)
        Note over MCP,ODE: ④ RE-AUTH — upstream session expired
        MCP->>ODE: GET /v3/nexus/... (Bearer stale apiSessionToken)
        ODE-->>MCP: 401 Unauthorized
        Note right of MCP: apiSessionToken = null
single-flight re-login
        MCP->>ODE: POST /v3/user/login · name, pwd
        ODE-->>MCP: 200 new sessionID
        MCP->>ODE: GET /v3/nexus/... (Bearer new apiSessionToken) — retry once
        ODE-->>MCP: 200 records
    end