SCAL-319970 Add OAuth-gated list_orgs tool

[rohitthughtspot]

Here's a PR-ready version that includes the Mermaid diagram and the accompanying design notes.

Multi-Org MCP — Request & Token Flow

This diagram illustrates how the org management tools (list_orgs / switch_org), org-scoped token lifecycle, background keep-warm mechanism, and analysis conversations work together.

sequenceDiagram
    autonumber

    participant Client as MCP Client
    participant MCP as MCP Worker
    participant UTS as UserTokenStore DO
    participant CONV as Conversation DO
    participant TS as ThoughtSpot

    Note over Client,TS: Two token types
    Note over Client,TS: GLOBAL = keep-warm, list_orgs, org-token minting
    Note over Client,TS: ORG = data APIs with x-thoughtspot-orgs header
    Note over Client,TS: Org behavior applies only for OAuth + Orgs-enabled + v2

    rect rgba(180,180,180,0.15)
        Note over Client,TS: Initialization

        Client->>MCP: initialize
        Note over MCP: postInit (best effort)

        MCP->>UTS: GET token-store

        alt Unseeded or stored token expired
            MCP->>UTS: POST token-store (seed + arm 11h alarm)
            Note right of UTS: Re-seeding an expired token heals a broken refresh chain
        end

        MCP->>UTS: GET active-org

        alt No active org
            MCP->>UTS: POST active-org (session default)
        end

        MCP->>TS: Mint org token (GLOBAL)
        TS-->>MCP: Org-scoped token
        MCP->>UTS: Persist active-org token
    end

    rect rgba(180,180,180,0.15)
        Note over Client,TS: Every tool call

        Client->>MCP: Tool call
        MCP->>UTS: POST touch (OAuth only, throttled)
        Note right of UTS: Refresh 14-day idle TTL
    end

    rect rgba(180,180,180,0.15)
        Note over Client,TS: list_orgs

        Client->>MCP: list_orgs
        MCP->>TS: GET session orgs (GLOBAL)
        TS-->>MCP: User orgs
        MCP->>UTS: GET active-org
        MCP-->>Client: Orgs (active org flagged)
    end

    rect rgba(180,180,180,0.15)
        Note over Client,TS: switch_org (mint-first)

        Client->>MCP: switch_org(orgId)

        MCP->>TS: Mint org token (GLOBAL)

        alt Invalid or inaccessible org
            TS-->>MCP: 400 / 401 / 403
            MCP-->>Client: No-op (active org unchanged)
        else Success
            TS-->>MCP: Org-scoped token
            MCP->>UTS: Atomically persist org + token
            MCP-->>Client: Switched
        end
    end

    rect rgba(180,180,180,0.15)
        Note over Client,TS: Analysis session

        Client->>MCP: create_analysis_session()

        MCP->>TS: POST conversation v2 (ORG token + org header)

        alt Org token stale
            TS-->>MCP: 401
            MCP->>UTS: Evict stale org token
            MCP->>TS: Mint fresh org token (GLOBAL)
            TS-->>MCP: Fresh org token
            MCP->>UTS: Persist token
            MCP->>TS: Retry conversation once
        end

        TS-->>MCP: analytical_session_id
        MCP-->>Client: analytical_session_id

        Note over Client,MCP: Query is sent in the next step
    end

    rect rgba(180,180,180,0.15)
        Note over Client,TS: Send message

        Client->>MCP: send_session_message(session_id, message)

        MCP->>CONV: Initialize conversation
        MCP->>TS: Stream message

        loop Streaming
            TS-->>MCP: Chunk
            MCP->>CONV: Append chunk
        end

        MCP-->>Client: OK
    end

    rect rgba(180,180,180,0.15)
        Note over Client,TS: Poll updates

        Client->>MCP: get_session_updates()

        loop Until complete
            MCP->>CONV: GET messages
            CONV-->>MCP: Messages + isDone
        end

        MCP-->>Client: Session updates
    end

    rect rgba(180,180,180,0.15)
        Note over Client,TS: Background keep-warm

        Note over UTS: 11-hour alarm

        alt Idle for less than 14 days
            UTS->>TS: Refresh global token
            TS-->>UTS: Fresh global token
            Note right of UTS: Re-arm 11-hour alarm
        else Idle for 14 days or more
            Note over UTS: Delete token store and active org
        end
    end

    Note over MCP,UTS: Active org is shared per user
    Note over MCP,UTS: Durable Object serializes updates
    Note over MCP,UTS: Last successful switch wins

Loading

Key Design Points

• Two token types.

  • Global token: Cluster-wide OAuth token kept warm by the UserTokenStore alarm. Used for list_orgs and minting org-scoped tokens. No org header is required.
  • Org-scoped token: Bound to a single organization and used for all data APIs together with the x-thoughtspot-orgs header.

• v2-only behavior. Multi-org support is enabled only for OAuth authentication on org-enabled clusters using the v2 APIs. Bearer-token authentication and v1 APIs retain the existing single-org behavior.

• Shared per-user state. Active org and cached tokens are stored in a single UserTokenStore Durable Object keyed by hash(refreshToken). This allows all client sessions for a user to share the same active org and avoids redundant org-token minting. The trade-off is that the active org is per user, so the most recent successful switch_org becomes the active org for all sessions.

• Mint-first switching. switch_org validates the requested organization by minting an org-scoped token before updating state. Invalid or inaccessible org IDs leave the active org unchanged.

• Resilient token handling. If an org-scoped token becomes invalid, the worker transparently re-mints it after a single 401 response and retries the request once. The background keep-warm process refreshes the global OAuth token every 11 hours, re-arms itself on failure, and removes stale state after 14 days of inactivity, requiring the user to authenticate again.

[gemini-code-assist]

Code Review

This pull request introduces the list_orgs tool, which is restricted to OAuth-authenticated connections. It adds the necessary schemas, types, and service methods to search and list active Orgs from the ThoughtSpot instance. Feedback on these changes suggests fetching session info dynamically to ensure current_org_id is reliably populated, and adding a defensive nullish coalescing guard when filtering the upstream Orgs response to prevent potential runtime errors.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The orgs returned from this.client.searchOrgs could potentially be null or undefined if the upstream API returns an empty or unexpected response. To prevent a runtime TypeError when calling .filter() on a nullish value, we should add a defensive nullish coalescing guard (orgs ?? []).

Suggested change

	const results: Org[] = orgs
	.filter(
	(org): org is typeof org & { id: number } =>
	typeof org.id === "number" && org.status === "ACTIVE",
	)
	const results: Org[] = (orgs ?? [])
	.filter(
	(org): org is typeof org & { id: number } =>
	typeof org.id === "number" && org.status === "ACTIVE",
	)