@mcp-ts/sdk 2.3.3 → 2.4.0

package/src/client/react/use-mcp.ts

@@ -6,6 +6,11 @@
 
 import { useEffect, useRef, useState, useCallback, useMemo } from 'react';
 import { SSEClient, type SSEClientOptions } from '../core/sse-client';
+import {
+  getInitialConnectionState,
+  getVisibleConnectionState,
+  isTransientReconnectState,
+} from '../utils/session-state';
 import type { McpConnectionEvent, McpConnectionState } from '../../shared/events';
 import type {
   ToolInfo,
@@ -84,6 +89,7 @@ export interface McpConnection {
   authUrl?: string;
   error?: string;
   createdAt?: Date;
+  updatedAt?: Date;
 }
 
 export interface McpClient {
@@ -167,7 +173,7 @@ export interface McpClient {
   /**
    * Complete OAuth authorization
    */
-  finishAuth: (sessionId: string, code: string) => Promise<FinishAuthResult>;
+  finishAuth: (state: string, code: string) => Promise<FinishAuthResult>;
 
   /**
    * Explicitly resume OAuth flow for an existing session
@@ -293,42 +299,6 @@ export function useMcp(options: UseMcpOptions): McpClient {
   const updateConnectionsFromEvent = useCallback((event: McpConnectionEvent) => {
     if (!isMountedRef.current) return;
 
-    const isTransientReconnectState = (state: McpConnectionState): boolean =>
-      state === 'INITIALIZING' ||
-      state === 'VALIDATING' ||
-      state === 'RECONNECTING' ||
-      state === 'CONNECTING' ||
-      state === 'CONNECTED' ||
-      state === 'DISCOVERING';
-
-    const getVisibleState = (
-      incomingState: McpConnectionState,
-      existingState?: McpConnectionState,
-      previousState?: McpConnectionState
-    ): McpConnectionState => {
-      // `INITIALIZING` has two meanings in practice:
-      // 1. genuine cold start / reconnect work
-      // 2. an internal setup step that happens mid-OAuth completion
-      //
-      // For case (2), showing raw `INITIALIZING` creates a confusing user-facing
-      // sequence like AUTHENTICATING -> INITIALIZING -> AUTHENTICATED.
-      // We keep the raw event stream intact for observability, but collapse the
-      // visible state back into the current auth phase in the UI.
-      if (
-        incomingState === 'INITIALIZING' &&
-        (existingState === 'AUTHENTICATING' ||
-          existingState === 'AUTHENTICATED' ||
-          previousState === 'AUTHENTICATING' ||
-          previousState === 'AUTHENTICATED')
-      ) {
-        return existingState === 'AUTHENTICATED' || previousState === 'AUTHENTICATED'
-          ? 'AUTHENTICATED'
-          : 'AUTHENTICATING';
-      }
-
-      return incomingState;
-    };
-
     setConnections((prev: McpConnection[]) => {
       switch (event.type) {
         case 'state_changed': {
@@ -336,7 +306,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
           if (existing) {
             // Normalize the incoming backend state into the smoother user-facing
             // state we want to render for this existing connection.
-            const normalizedState = getVisibleState(event.state, existing.state, event.previousState);
+            const normalizedState = getVisibleConnectionState(event.state, existing.state, event.previousState);
             // In stateless per-request transport, tool calls can emit transient reconnect states.
             // Keep READY sticky to avoid UI flicker from READY -> CONNECTING -> CONNECTED.
             const nextState =
@@ -344,12 +314,14 @@ export function useMcp(options: UseMcpOptions): McpClient {
                 ? existing.state
                 : normalizedState;
 
+            const updatedAt = new Date();
             return prev.map((c: McpConnection) =>
               c.sessionId === event.sessionId ? {
                 ...c,
                 state: nextState,
                 // update createdAt if present in event, otherwise keep existing
-                createdAt: event.createdAt ? new Date(event.createdAt) : c.createdAt
+                createdAt: event.createdAt ? new Date(event.createdAt) : c.createdAt,
+                updatedAt,
               } : c
             );
           } else {
@@ -367,8 +339,9 @@ export function useMcp(options: UseMcpOptions): McpClient {
                 serverUrl: event.serverUrl,
                 // New connections do not have prior local state, so we normalize
                 // only against the server-reported previous state.
-                state: getVisibleState(event.state, undefined, event.previousState),
+                state: getVisibleConnectionState(event.state, undefined, event.previousState),
                 createdAt: event.createdAt ? new Date(event.createdAt) : undefined,
+                updatedAt: new Date(),
                 tools: [],
               },
             ];
@@ -382,7 +355,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
           }
 
           return prev.map((c: McpConnection) =>
-            c.sessionId === event.sessionId ? { ...c, tools: event.tools, state: 'READY' } : c
+            c.sessionId === event.sessionId ? { ...c, tools: event.tools, state: 'READY', updatedAt: new Date() } : c
           );
         }
 
@@ -453,8 +426,9 @@ export function useMcp(options: UseMcpOptions): McpClient {
             serverName: s.serverName ?? 'Unknown Server',
             serverUrl: s.serverUrl,
             transport: s.transport,
-            state: (s.active === false ? 'AUTHENTICATING' : 'VALIDATING') as McpConnectionState,
+            state: getInitialConnectionState(s.status),
             createdAt: new Date(s.createdAt),
+            updatedAt: new Date(s.updatedAt ?? s.createdAt),
             tools: [],
           }))
         );
@@ -466,7 +440,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
           if (clientRef.current) {
             try {
               // Pending auth sessions should not auto-trigger popup/redirect on reload.
-              if (session.active === false) {
+              if (session.status !== 'active') {
                 return;
               }
               suppressAuthRedirectSessionsRef.current.add(session.sessionId);
@@ -585,12 +559,12 @@ export function useMcp(options: UseMcpOptions): McpClient {
   /**
    * Complete OAuth authorization
    */
-  const finishAuth = useCallback(async (sessionId: string, code: string): Promise<FinishAuthResult> => {
+  const finishAuth = useCallback(async (state: string, code: string): Promise<FinishAuthResult> => {
     if (!clientRef.current) {
       throw new Error('SSE client not initialized');
     }
 
-    return await clientRef.current.finishAuth(sessionId, code);
+    return await clientRef.current.finishAuth(state, code);
   }, []);
 
   /**

package/src/client/utils/session-state.ts

@@ -0,0 +1,43 @@
+import type { McpConnectionState } from '../../shared/events';
+import type { SessionInfo } from '../../shared/types';
+
+export function getInitialConnectionState(status: SessionInfo['status']): McpConnectionState {
+    return status === 'active' ? 'VALIDATING' : 'AUTHENTICATING';
+}
+
+export function isTransientReconnectState(state: McpConnectionState): boolean {
+    return state === 'INITIALIZING' ||
+        state === 'VALIDATING' ||
+        state === 'RECONNECTING' ||
+        state === 'CONNECTING' ||
+        state === 'CONNECTED' ||
+        state === 'DISCOVERING';
+}
+
+export function getVisibleConnectionState(
+    incomingState: McpConnectionState,
+    existingState?: McpConnectionState,
+    previousState?: McpConnectionState
+): McpConnectionState {
+    // `INITIALIZING` has two meanings in practice:
+    // 1. genuine cold start / reconnect work
+    // 2. an internal setup step that happens mid-OAuth completion
+    //
+    // For case (2), showing raw `INITIALIZING` creates a confusing user-facing
+    // sequence like AUTHENTICATING -> INITIALIZING -> AUTHENTICATED.
+    if (
+        incomingState === 'INITIALIZING' &&
+        (
+            existingState === 'AUTHENTICATING' ||
+            existingState === 'AUTHENTICATED' ||
+            previousState === 'AUTHENTICATING' ||
+            previousState === 'AUTHENTICATED'
+        )
+    ) {
+        return existingState === 'AUTHENTICATED' || previousState === 'AUTHENTICATED'
+            ? 'AUTHENTICATED'
+            : 'AUTHENTICATING';
+    }
+
+    return incomingState;
+}

package/src/client/vue/use-mcp.ts

@@ -6,6 +6,11 @@
 
 import { ref, onMounted, onUnmounted, watch, computed, shallowRef } from 'vue';
 import { SSEClient, type SSEClientOptions } from '../core/sse-client';
+import {
+    getInitialConnectionState,
+    getVisibleConnectionState,
+    isTransientReconnectState,
+} from '../utils/session-state';
 import type { McpConnectionEvent, McpConnectionState } from '../../shared/events';
 import type {
     ToolInfo,
@@ -83,6 +88,7 @@ export interface McpConnection {
     authUrl?: string;
     error?: string;
     createdAt?: Date;
+    updatedAt?: Date;
 }
 
 export interface McpClient {
@@ -166,7 +172,7 @@ export interface McpClient {
     /**
      * Complete OAuth authorization
      */
-    finishAuth: (sessionId: string, code: string) => Promise<FinishAuthResult>;
+    finishAuth: (state: string, code: string) => Promise<FinishAuthResult>;
 
     /**
      * Explicitly resume OAuth flow for an existing session
@@ -243,51 +249,13 @@ export function useMcp(options: UseMcpOptions): McpClient {
     const updateConnectionsFromEvent = (event: McpConnectionEvent) => {
         if (!isMountedRef.value) return;
 
-        const isTransientReconnectState = (state: McpConnectionState): boolean =>
-            state === 'INITIALIZING' ||
-            state === 'VALIDATING' ||
-            state === 'RECONNECTING' ||
-            state === 'CONNECTING' ||
-            state === 'CONNECTED' ||
-            state === 'DISCOVERING';
-
-        const getVisibleState = (
-            incomingState: McpConnectionState,
-            existingState?: McpConnectionState,
-            previousState?: McpConnectionState
-        ): McpConnectionState => {
-            // `INITIALIZING` has two meanings in practice:
-            // 1. genuine cold start / reconnect work
-            // 2. an internal setup step that happens mid-OAuth completion
-            //
-            // For case (2), showing raw `INITIALIZING` creates a confusing user-facing
-            // sequence like AUTHENTICATING -> INITIALIZING -> AUTHENTICATED.
-            // We keep the raw event stream intact for observability, but collapse the
-            // visible state back into the current auth phase in the UI.
-            if (
-                incomingState === 'INITIALIZING' &&
-                (
-                    existingState === 'AUTHENTICATING' ||
-                    existingState === 'AUTHENTICATED' ||
-                    previousState === 'AUTHENTICATING' ||
-                    previousState === 'AUTHENTICATED'
-                )
-            ) {
-                return existingState === 'AUTHENTICATED' || previousState === 'AUTHENTICATED'
-                    ? 'AUTHENTICATED'
-                    : 'AUTHENTICATING';
-            }
-
-            return incomingState;
-        };
-
         switch (event.type) {
             case 'state_changed': {
                 const existing = connections.value.find((c) => c.sessionId === event.sessionId);
                 if (existing) {
                     // Normalize the incoming backend state into the smoother user-facing
                     // state we want to render for this existing connection.
-                    const normalizedState = getVisibleState(event.state, existing.state, event.previousState);
+                    const normalizedState = getVisibleConnectionState(event.state, existing.state, event.previousState);
                     // In stateless per-request transport, tool calls can emit transient reconnect states.
                     // Keep READY sticky to avoid UI flicker from READY -> CONNECTING -> CONNECTED.
                     const nextState =
@@ -300,7 +268,8 @@ export function useMcp(options: UseMcpOptions): McpClient {
                         ...existing,
                         state: nextState,
                         // update createdAt if present in event, otherwise keep existing
-                        createdAt: event.createdAt ? new Date(event.createdAt) : existing.createdAt
+                        createdAt: event.createdAt ? new Date(event.createdAt) : existing.createdAt,
+                        updatedAt: new Date(),
                     };
                 } else {
                     // Fix: Don't add back disconnected sessions that were just removed
@@ -314,8 +283,9 @@ export function useMcp(options: UseMcpOptions): McpClient {
                         serverName: event.serverName,
                         // New connections do not have prior local state, so we normalize
                         // only against the server-reported previous state.
-                        state: getVisibleState(event.state, undefined, event.previousState),
+                        state: getVisibleConnectionState(event.state, undefined, event.previousState),
                         createdAt: event.createdAt ? new Date(event.createdAt) : undefined,
+                        updatedAt: new Date(),
                         tools: [],
                     }];
                 }
@@ -325,7 +295,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
             case 'tools_discovered': {
                 const index = connections.value.findIndex((c) => c.sessionId === event.sessionId);
                 if (index !== -1) {
-                    connections.value[index] = { ...connections.value[index], tools: event.tools, state: 'READY' };
+                    connections.value[index] = { ...connections.value[index], tools: event.tools, state: 'READY', updatedAt: new Date() };
                 }
                 break;
             }
@@ -397,8 +367,9 @@ export function useMcp(options: UseMcpOptions): McpClient {
                     serverName: s.serverName ?? 'Unknown Server',
                     serverUrl: s.serverUrl,
                     transport: s.transport,
-                    state: (s.active === false ? 'AUTHENTICATING' : 'VALIDATING') as McpConnectionState,
+                    state: getInitialConnectionState(s.status),
                     createdAt: new Date(s.createdAt),
+                    updatedAt: new Date(s.updatedAt ?? s.createdAt),
                     tools: [],
                 }));
             }
@@ -409,7 +380,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
                     if (clientRef.value) {
                         try {
                             // Pending auth sessions should not auto-trigger popup/redirect on reload.
-                            if (session.active === false) {
+                            if (session.status !== 'active') {
                                 return;
                             }
                             suppressAuthRedirectSessions.value.add(session.sessionId);
@@ -573,12 +544,12 @@ export function useMcp(options: UseMcpOptions): McpClient {
     /**
      * Complete OAuth authorization
      */
-    const finishAuth = async (sessionId: string, code: string): Promise<FinishAuthResult> => {
+    const finishAuth = async (state: string, code: string): Promise<FinishAuthResult> => {
         if (!clientRef.value) {
             throw new Error('SSE client not initialized');
         }
 
-        return await clientRef.value.finishAuth(sessionId, code);
+        return await clientRef.value.finishAuth(state, code);
     };
 
     /**

package/src/server/handlers/sse-handler.ts

@@ -36,6 +36,7 @@ import type {
 import { RpcErrorCodes } from '../../shared/errors.js';
 import { UnauthorizedError } from '../../shared/errors.js';
 import { isConnectionEvent, isRpcResponseEvent } from '../../shared/event-routing.js';
+import { parseOAuthState } from '../../shared/utils.js';
 import { MCPClient } from '../mcp/oauth-client.js';
 import { sessions } from '../storage/index.js';
 
@@ -238,7 +239,8 @@ export class SSEConnectionManager {
         serverUrl: s.serverUrl,
         transport: s.transportType,
         createdAt: s.createdAt,
-        active: s.active !== false,
+        updatedAt: s.updatedAt ?? s.createdAt,
+        status: s.status ?? 'pending',
       })),
     };
   }
@@ -265,7 +267,7 @@ export class SSEConnectionManager {
     if (duplicate) {
       // If the existing session is still pending OAuth, treat connect as "resume auth"
       // instead of failing with duplicate connection error.
-      if (duplicate.active === false) {
+      if (duplicate.status === 'pending') {
         await this.getSession({ sessionId: duplicate.sessionId });
         return {
           sessionId: duplicate.sessionId,
@@ -504,7 +506,10 @@ export class SSEConnectionManager {
    * Complete OAuth authorization flow
    */
   private async finishAuth(params: FinishAuthParams): Promise<FinishAuthResult> {
-    const { sessionId, code } = params;
+    const { code } = params;
+    const oauthState = params.state;
+    const parsedState = parseOAuthState(oauthState);
+    const sessionId = parsedState?.sessionId || oauthState;
 
     const session = await sessions.get(this.userId, sessionId);
     if (!session) {
@@ -533,7 +538,7 @@ export class SSEConnectionManager {
 
       client.onConnectionEvent((event) => this.emitConnectionEvent(event));
 
-      await client.finishAuth(code);
+      await client.finishAuth(code, oauthState);
       this.clients.set(sessionId, client);
 
       const tools = await client.listTools();

package/src/server/mcp/multi-session-client.ts

@@ -66,12 +66,8 @@ export class MultiSessionClient {
      *
      * A session is considered connectable when:
      * - It has a `serverId`, `serverUrl`, and `callbackUrl` (i.e. it was fully initialized)
-     * - Its `active` flag is not explicitly `false` — sessions with `active: false` are
-     *   either mid-OAuth flow, auth-pending, or previously failed. We skip those here
+     * - Its status is `active`. Pending sessions are skipped here
      *   and let the OAuth flow complete separately before we try to reconnect them.
-     *
-     * Note: Sessions where `active` is `undefined` (legacy records) are included
-     * for backwards compatibility.
      */
     private async getActiveSessions(): Promise<Session[]> {
         const sessionList = await sessions.list(this.userId);
@@ -79,7 +75,7 @@ export class MultiSessionClient {
             s.serverId &&
             s.serverUrl &&
             s.callbackUrl &&
-            s.active !== false  // exclude OAuth-pending / failed sessions
+            s.status === 'active'
         );
         return valid;
     }