@mcp-ts/sdk 2.3.4 → 2.4.0

package/dist/{tool-router-BMzhoNYt.d.ts → tool-router-CZMrOG8J.d.ts}

@@ -1,5 +1,5 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import { u as ToolClientProvider, T as ToolClient } from './types-CxFaaZrM.js';
+import { u as ToolClientProvider, T as ToolClient } from './types-DCk_IF4L.js';
 
 /**
  * ToolIndex — Lightweight in-memory search index for MCP tool discovery.

package/dist/{tool-router-BhHsvBfP.d.mts → tool-router-CuApsDiV.d.mts}

@@ -1,5 +1,5 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import { u as ToolClientProvider, T as ToolClient } from './types-CxFaaZrM.mjs';
+import { u as ToolClientProvider, T as ToolClient } from './types-DCk_IF4L.mjs';
 
 /**
  * ToolIndex — Lightweight in-memory search index for MCP tool discovery.

package/dist/{types-CxFaaZrM.d.mts → types-DCk_IF4L.d.mts}

@@ -83,6 +83,7 @@ type ToolInfo = {
     outputSchema?: Tool['outputSchema'];
 };
 type TransportType = 'sse' | 'streamable-http';
+type SessionStatus = 'pending' | 'active';
 type McpRpcMethod = 'connect' | 'disconnect' | 'listTools' | 'callTool' | 'listSessions' | 'getSession' | 'finishAuth' | 'listPrompts' | 'getPrompt' | 'listResources' | 'readResource';
 interface McpRpcRequest {
     id: string;
@@ -126,7 +127,7 @@ interface ReadResourceParams {
     uri: string;
 }
 interface FinishAuthParams {
-    sessionId: string;
+    state: string;
     code: string;
 }
 type McpRpcParams = ConnectParams | DisconnectParams | SessionParams | CallToolParams | GetPromptParams | ReadResourceParams | FinishAuthParams | undefined;
@@ -137,11 +138,12 @@ interface SessionInfo {
     serverUrl: string;
     transport: TransportType;
     createdAt: number;
+    updatedAt?: number;
     /**
      * Session readiness for auto-restore.
-     * false means auth is pending and should be resumed explicitly by user action.
+     * `pending` means auth is in progress and should be resumed explicitly by user action.
      */
-    active?: boolean;
+    status: SessionStatus;
 }
 interface SessionListResult {
     sessions: SessionInfo[];

package/dist/{types-CxFaaZrM.d.ts → types-DCk_IF4L.d.ts}

@@ -83,6 +83,7 @@ type ToolInfo = {
     outputSchema?: Tool['outputSchema'];
 };
 type TransportType = 'sse' | 'streamable-http';
+type SessionStatus = 'pending' | 'active';
 type McpRpcMethod = 'connect' | 'disconnect' | 'listTools' | 'callTool' | 'listSessions' | 'getSession' | 'finishAuth' | 'listPrompts' | 'getPrompt' | 'listResources' | 'readResource';
 interface McpRpcRequest {
     id: string;
@@ -126,7 +127,7 @@ interface ReadResourceParams {
     uri: string;
 }
 interface FinishAuthParams {
-    sessionId: string;
+    state: string;
     code: string;
 }
 type McpRpcParams = ConnectParams | DisconnectParams | SessionParams | CallToolParams | GetPromptParams | ReadResourceParams | FinishAuthParams | undefined;
@@ -137,11 +138,12 @@ interface SessionInfo {
     serverUrl: string;
     transport: TransportType;
     createdAt: number;
+    updatedAt?: number;
     /**
      * Session readiness for auto-restore.
-     * false means auth is pending and should be resumed explicitly by user action.
+     * `pending` means auth is in progress and should be resumed explicitly by user action.
      */
-    active?: boolean;
+    status: SessionStatus;
 }
 interface SessionListResult {
     sessions: SessionInfo[];

package/migrations/neon/20260513010000_install_mcp_sessions.sql

@@ -12,17 +12,38 @@ CREATE TABLE IF NOT EXISTS public.mcp_sessions (
     callback_url TEXT NOT NULL,
     created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
     updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-    expires_at TIMESTAMPTZ NOT NULL,
-    active BOOLEAN DEFAULT false,
+    expires_at TIMESTAMPTZ,
+    status TEXT NOT NULL DEFAULT 'pending'
+        CHECK (status IN ('pending', 'active')),
     headers JSONB,
+    auth_url TEXT,
+    CONSTRAINT mcp_sessions_user_session_unique
+        UNIQUE (user_id, session_id)
+);
+
+CREATE TABLE IF NOT EXISTS public.mcp_credentials (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    session_id TEXT NOT NULL,
+    user_id TEXT NOT NULL,
     client_information JSONB,
     tokens JSONB,
     code_verifier TEXT,
-    client_id TEXT
+    client_id TEXT,
+    oauth_state JSONB,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    CONSTRAINT mcp_credentials_session_fk
+        FOREIGN KEY (user_id, session_id)
+        REFERENCES public.mcp_sessions(user_id, session_id)
+        ON DELETE CASCADE,
+    CONSTRAINT mcp_credentials_user_session_unique
+        UNIQUE (user_id, session_id)
 );
 
 CREATE INDEX IF NOT EXISTS idx_mcp_sessions_user_id ON public.mcp_sessions(user_id);
 CREATE INDEX IF NOT EXISTS idx_mcp_sessions_expires_at ON public.mcp_sessions(expires_at);
+CREATE INDEX IF NOT EXISTS idx_mcp_credentials_user_session
+ON public.mcp_credentials(user_id, session_id);
 
 CREATE OR REPLACE FUNCTION public.set_current_timestamp_updated_at()
 RETURNS TRIGGER AS $$
@@ -39,6 +60,13 @@ BEFORE UPDATE ON public.mcp_sessions
 FOR EACH ROW
 EXECUTE FUNCTION public.set_current_timestamp_updated_at();
 
+DROP TRIGGER IF EXISTS trg_mcp_credentials_updated_at ON public.mcp_credentials;
+
+CREATE TRIGGER trg_mcp_credentials_updated_at
+BEFORE UPDATE ON public.mcp_credentials
+FOR EACH ROW
+EXECUTE FUNCTION public.set_current_timestamp_updated_at();
+
 -- Optional production configuration:
 -- Create a dedicated app role and use its credentials in NEON_DATABASE_URL.
 -- Replace neondb and the password before running.
@@ -47,6 +75,7 @@ EXECUTE FUNCTION public.set_current_timestamp_updated_at();
 -- GRANT CONNECT ON DATABASE neondb TO mcp_service_role;
 -- GRANT USAGE ON SCHEMA public TO mcp_service_role;
 -- GRANT SELECT, INSERT, UPDATE, DELETE ON public.mcp_sessions TO mcp_service_role;
+-- GRANT SELECT, INSERT, UPDATE, DELETE ON public.mcp_credentials TO mcp_service_role;
 -- GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO mcp_service_role;
 
 -- Optional RLS configuration:
@@ -60,6 +89,7 @@ EXECUTE FUNCTION public.set_current_timestamp_updated_at();
 -- GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO mcp_service_role;
 --
 -- ALTER TABLE public.mcp_sessions ENABLE ROW LEVEL SECURITY;
+-- ALTER TABLE public.mcp_credentials ENABLE ROW LEVEL SECURITY;
 --
 -- CREATE POLICY mcp_service_role_full_access
 -- ON public.mcp_sessions
@@ -67,3 +97,10 @@ EXECUTE FUNCTION public.set_current_timestamp_updated_at();
 -- TO mcp_service_role
 -- USING (true)
 -- WITH CHECK (true);
+--
+-- CREATE POLICY mcp_service_role_oauth_full_access
+-- ON public.mcp_credentials
+-- FOR ALL
+-- TO mcp_service_role
+-- USING (true)
+-- WITH CHECK (true);

package/migrations/neon/20260513020000_add_session_cleanup_cron.sql

@@ -18,12 +18,12 @@ WHERE jobname IN (
 );
 
 -- Stage 1: Short-term Transient Purge (every 5 minutes)
--- Removes failed connections, abandoned OAuth flows, and other inactive
--- sessions whose TTL has expired.
+-- Removes abandoned OAuth flows and other transient
+-- sessions whose pending expiration has passed.
 SELECT cron.schedule(
     'mcp-cleanup-transient-sessions',
     '*/5 * * * *',
-    $$DELETE FROM public.mcp_sessions WHERE expires_at < now() AND active IS NOT TRUE;$$
+    $$DELETE FROM public.mcp_sessions WHERE expires_at IS NOT NULL AND expires_at < now() AND status <> 'active';$$
 );
 
 -- Stage 2: Long-term Dormancy Eviction (daily at midnight UTC)
@@ -31,5 +31,5 @@ SELECT cron.schedule(
 SELECT cron.schedule(
     'mcp-cleanup-dormant-sessions',
     '0 0 * * *',
-    $$DELETE FROM public.mcp_sessions WHERE active = true AND updated_at < now() - interval '30 days';$$
+    $$DELETE FROM public.mcp_sessions WHERE status = 'active' AND updated_at < now() - interval '30 days';$$
 );

package/migrations/supabase/20260330195700_install_mcp_sessions.sql

@@ -10,19 +10,41 @@ CREATE TABLE IF NOT EXISTS public.mcp_sessions (
     callback_url TEXT NOT NULL,
     created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
     updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-    expires_at TIMESTAMPTZ NOT NULL,
-    active BOOLEAN DEFAULT false,
+    expires_at TIMESTAMPTZ,
+    status TEXT NOT NULL DEFAULT 'pending'
+        CHECK (status IN ('pending', 'active')),
     headers JSONB,
+    auth_url TEXT,
+    CONSTRAINT mcp_sessions_user_session_unique
+        UNIQUE (user_id, session_id)
+);
+
+-- Runtime credentials are kept separate from connection metadata.
+CREATE TABLE IF NOT EXISTS public.mcp_credentials (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    session_id TEXT NOT NULL,
+    user_id TEXT NOT NULL,
     client_information JSONB,
     tokens JSONB,
     code_verifier TEXT,
-    client_id TEXT
+    client_id TEXT,
+    oauth_state JSONB,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    CONSTRAINT mcp_credentials_session_fk
+        FOREIGN KEY (user_id, session_id)
+        REFERENCES public.mcp_sessions(user_id, session_id)
+        ON DELETE CASCADE,
+    CONSTRAINT mcp_credentials_user_session_unique
+        UNIQUE (user_id, session_id)
 );
 
 -- Add an index on user_id for faster lookups
 CREATE INDEX IF NOT EXISTS idx_mcp_sessions_user_id ON public.mcp_sessions(user_id);
 -- Add an index on expires_at to speed up the cleanup job
 CREATE INDEX IF NOT EXISTS idx_mcp_sessions_expires_at ON public.mcp_sessions(expires_at);
+CREATE INDEX IF NOT EXISTS idx_mcp_credentials_user_session
+ON public.mcp_credentials(user_id, session_id);
 
 -- Trigger to automatically update the 'updated_at' column
 CREATE OR REPLACE FUNCTION public.set_current_timestamp_updated_at()
@@ -39,8 +61,15 @@ BEFORE UPDATE ON public.mcp_sessions
 FOR EACH ROW
 EXECUTE FUNCTION public.set_current_timestamp_updated_at();
 
+DROP TRIGGER IF EXISTS trg_mcp_credentials_updated_at ON public.mcp_credentials;
+CREATE TRIGGER trg_mcp_credentials_updated_at
+BEFORE UPDATE ON public.mcp_credentials
+FOR EACH ROW
+EXECUTE FUNCTION public.set_current_timestamp_updated_at();
+
 -- Enable Row Level Security (RLS)
 ALTER TABLE public.mcp_sessions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.mcp_credentials ENABLE ROW LEVEL SECURITY;
 
 -- Policy 1: Users can read their own sessions
 CREATE POLICY "Users can view their own sessions"
@@ -51,6 +80,14 @@ USING (
     auth.uid()::text = user_id
 );
 
+CREATE POLICY "Users can view their own credentials"
+ON public.mcp_credentials
+FOR SELECT
+TO authenticated
+USING (
+    auth.uid()::text = user_id
+);
+
 -- Policy 2: Users can insert their own sessions
 CREATE POLICY "Users can insert their own sessions"
 ON public.mcp_sessions
@@ -60,6 +97,14 @@ WITH CHECK (
     auth.uid()::text = user_id
 );
 
+CREATE POLICY "Users can insert their own credentials"
+ON public.mcp_credentials
+FOR INSERT
+TO authenticated
+WITH CHECK (
+    auth.uid()::text = user_id
+);
+
 -- Policy 3: Users can update their own sessions
 CREATE POLICY "Users can update their own sessions"
 ON public.mcp_sessions
@@ -72,6 +117,17 @@ WITH CHECK (
     auth.uid()::text = user_id
 );
 
+CREATE POLICY "Users can update their own credentials"
+ON public.mcp_credentials
+FOR UPDATE
+TO authenticated
+USING (
+    auth.uid()::text = user_id
+)
+WITH CHECK (
+    auth.uid()::text = user_id
+);
+
 -- Policy 4: Users can delete their own sessions
 CREATE POLICY "Users can delete their own sessions"
 ON public.mcp_sessions
@@ -80,3 +136,11 @@ TO authenticated
 USING (
     auth.uid()::text = user_id
 );
+
+CREATE POLICY "Users can delete their own credentials"
+ON public.mcp_credentials
+FOR DELETE
+TO authenticated
+USING (
+    auth.uid()::text = user_id
+);

package/migrations/supabase/20260421010000_add_session_cleanup_cron.sql

@@ -5,27 +5,27 @@ CREATE EXTENSION IF NOT EXISTS pg_cron;
 -- ─────────────────────────────────────────────────────────────────────────────
 -- Stage 1: Short-term Transient Purge (every 5 minutes)
 -- ─────────────────────────────────────────────────────────────────────────────
--- Targets sessions that are NOT active (failed connections, abandoned OAuth
--- flows, mid-flow errors) whose TTL has expired. Active sessions are explicitly
+-- Targets transient sessions (pending OAuth or setup states) whose
+-- expiration has passed. Active sessions are explicitly
 -- excluded from this sweep to preserve automation credentials.
 --
 -- The idx_mcp_sessions_expires_at index ensures this is a fast indexed scan.
 SELECT cron.schedule(
     'cleanup-transient-sessions',
     '*/5 * * * *',
-    $$DELETE FROM public.mcp_sessions WHERE expires_at < now() AND active IS NOT TRUE;$$
+    $$DELETE FROM public.mcp_sessions WHERE expires_at IS NOT NULL AND expires_at < now() AND status <> 'active';$$
 );
 
 -- ─────────────────────────────────────────────────────────────────────────────
 -- Stage 2: Long-term Dormancy Eviction (daily at midnight UTC)
 -- ─────────────────────────────────────────────────────────────────────────────
--- Safety net for sessions that were successfully established (active = true)
--- but have been completely untouched for 30+ days. This prevents "active"
+-- Safety net for sessions that were successfully established (status = 'active')
+-- but have been completely untouched for 30+ days. This prevents active
 -- records from persisting indefinitely if they are genuinely abandoned.
 SELECT cron.schedule(
     'cleanup-dormant-sessions',
     '0 0 * * *',
-    $$DELETE FROM public.mcp_sessions WHERE active = true AND updated_at < now() - interval '30 days';$$
+    $$DELETE FROM public.mcp_sessions WHERE status = 'active' AND updated_at < now() - interval '30 days';$$
 );
 
 -- Add a comment on the extension for visibility in Supabase Dashboard

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@mcp-ts/sdk",
-  "version": "2.3.4",
+  "version": "2.4.0",
   "publishConfig": {
     "access": "public"
   },
-  "description": "A lightweight MCP (Model Context Protocol) client library for JavaScript and cross-runtime environments, supporting MCP Apps in host applications and multiple storage backends (Memory, File, Redis, Supabase, Neon).",
+  "description": "A lightweight MCP client library for TypeScript with durable sessions across Redis, Supabase, Neon, and SQLite, cross-runtime agent support, and dynamic tool discovery to reduce LLM context usage.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -102,7 +102,17 @@
     "react",
     "hook",
     "anthropic",
-    "claude"
+    "claude",
+    "typescript",
+    "agent",
+    "agents",
+    "durable-sessions",
+    "tool-discovery",
+    "tool-router",
+    "context-window",
+    "sqlite",
+    "supabase",
+    "neon"
   ],
   "author": "MCP Assistant Contributors",
   "license": "MIT",

package/src/client/core/sse-client.ts

@@ -117,8 +117,8 @@ export class SSEClient {
     return this.sendRequest<GetSessionResult>('getSession', { sessionId });
   }
 
-  async finishAuth(sessionId: string, code: string): Promise<FinishAuthResult> {
-    return this.sendRequest<FinishAuthResult>('finishAuth', { sessionId, code });
+  async finishAuth(state: string, code: string): Promise<FinishAuthResult> {
+    return this.sendRequest<FinishAuthResult>('finishAuth', { state, code });
   }
 
   async listPrompts(sessionId: string): Promise<ListPromptsResult> {

package/src/client/react/index.ts

@@ -8,7 +8,7 @@ export { useMcp, type UseMcpOptions, type McpClient, type McpConnection } from '
 
 // Optional OAuth popup conveniences. These are not required for auth:
 // consumers can still provide their own onRedirect handler, callback page UI,
-// or complete `finishAuth(sessionId, code)` from a normal redirect flow.
+// or complete `finishAuth(state, code)` from a normal redirect flow.
 export {
   useMcpOAuthPopup,
   openCenteredPopup,

package/src/client/react/oauth-popup.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react';
+import { parseOAuthState } from '../../shared/utils.js';
 
 export interface OAuthPopupConnectionLike {
   sessionId: string;
@@ -11,7 +12,7 @@ export interface OAuthPopupConnectionLike {
  *
  * These utilities sit on top of the core MCP auth primitives:
  * - `useMcp({ onRedirect })` to decide how auth navigation happens
- * - `finishAuth(sessionId, code)` to complete code exchange
+ * - `finishAuth(state, code)` to complete code exchange
  *
  * Consumers are free to:
  * - use these helpers as-is for a turnkey popup flow
@@ -60,6 +61,7 @@ function postPopupResult(
   popupWindow: WindowProxy | null,
   result: {
     sessionId?: string;
+    state?: string;
     success: boolean;
     error?: string;
   }
@@ -150,9 +152,9 @@ export function createOAuthPopupRedirectHandler(
  */
 export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
   connections: TConnection[],
-  finishAuth: (sessionId: string, code: string) => Promise<unknown>
+  finishAuth: (state: string, code: string) => Promise<unknown>
 ): void {
-  const pendingPopupsRef = useRef<Map<string, WindowProxy>>(new Map());
+  const pendingPopupsRef = useRef<Map<string, { popupWindow: WindowProxy | null; state: string }>>(new Map());
   const processingCodesRef = useRef<Set<string>>(new Set());
 
   useEffect(() => {
@@ -169,10 +171,16 @@ export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
       const popupWindow = event.source && 'postMessage' in event.source
         ? event.source as WindowProxy
         : null;
-      const targetSessionId = typeof event.data.sessionId === 'string' ? event.data.sessionId : '';
+      const rawState =
+        typeof event.data.state === 'string'
+          ? event.data.state
+          : typeof event.data.sessionId === 'string'
+            ? event.data.sessionId
+            : '';
+      const targetSessionId = rawState ? parseOAuthState(rawState)?.sessionId || rawState : '';
 
       if (popupWindow && targetSessionId) {
-        pendingPopupsRef.current.set(targetSessionId, popupWindow);
+        pendingPopupsRef.current.set(targetSessionId, { popupWindow, state: rawState });
       }
 
       if (!targetSessionId) {
@@ -190,6 +198,7 @@ export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
         if (popupWindow) {
           postPopupResult(popupWindow, {
             sessionId: targetSessionId,
+            state: rawState,
             success: false,
             error: 'OAuth session not found in the current client state',
           });
@@ -204,13 +213,14 @@ export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
       processingCodesRef.current.add(codeKey);
 
       try {
-        await finishAuth(targetSession.sessionId, code);
+        await finishAuth(rawState, code);
       } catch (error) {
         processingCodesRef.current.delete(codeKey);
         pendingPopupsRef.current.delete(targetSession.sessionId);
         if (popupWindow) {
           postPopupResult(popupWindow, {
-            sessionId: targetSession.sessionId,
+            sessionId: rawState,
+            state: rawState,
             success: false,
             error: error instanceof Error ? error.message : 'Failed to finish auth',
           });
@@ -237,11 +247,14 @@ export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
 
   useEffect(() => {
     for (const connection of connections) {
-      const popupWindow = pendingPopupsRef.current.get(connection.sessionId) || null;
+      const pendingPopup = pendingPopupsRef.current.get(connection.sessionId);
+      const popupWindow = pendingPopup?.popupWindow || null;
+      const resultState = pendingPopup?.state || connection.sessionId;
 
       if (connection.state === 'AUTHENTICATED' || connection.state === 'READY' || connection.state === 'CONNECTED') {
         postPopupResult(popupWindow, {
-          sessionId: connection.sessionId,
+          sessionId: resultState,
+          state: resultState,
           success: true,
         });
         for (const codeKey of processingCodesRef.current) {
@@ -255,7 +268,8 @@ export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
 
       if (connection.state === 'FAILED') {
         postPopupResult(popupWindow, {
-          sessionId: connection.sessionId,
+          sessionId: resultState,
+          state: resultState,
           success: false,
           error: connection.error || 'Failed to complete authorization',
         });
@@ -277,7 +291,7 @@ export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
  * opener window, waits for success/failure, and closes the popup on success.
  *
  * It is intentionally optional: apps can replace it with their own callback
- * page UI or skip popup auth entirely and call `finishAuth(sessionId, code)`
+ * page UI or skip popup auth entirely and call `finishAuth(state, code)`
  * from any callback route they control.
  */
 export function McpOAuthCallbackContent({
@@ -328,7 +342,14 @@ export function McpOAuthCallbackContent({
         return;
       }
 
-      if (event.data.sessionId !== sessionId) {
+      const resultState =
+        typeof event.data.state === 'string'
+          ? event.data.state
+          : typeof event.data.sessionId === 'string'
+            ? event.data.sessionId
+            : '';
+
+      if (resultState !== sessionId) {
         return;
       }
 
@@ -352,7 +373,7 @@ export function McpOAuthCallbackContent({
     window.addEventListener('message', handleResult);
     channel?.addEventListener('message', handleResult);
 
-    const payload = { type: AUTH_CODE_MESSAGE, code, sessionId };
+    const payload = { type: AUTH_CODE_MESSAGE, code, state: sessionId, sessionId };
 
     if (window.opener) {
       try {