Align MCP refresh responses with publication order (#5754)

Expose discovery publication metadata to refresh callers, report live tools during cache degradation, and compare lastToolsRefresh mutation tokens instead of wall clocks when preserving a newer success.

Author: j15z

apps/sim/app/api/mcp/servers/[id]/refresh/route.test.ts

@@ -43,7 +43,7 @@ vi.mock('@/lib/mcp/middleware', () => ({
 vi.mock('@/lib/mcp/service', () => ({
   mcpService: {
     clearCache: mockClearCache,
-    discoverServerTools: mockDiscoverServerTools,
+    discoverServerToolsWithMetadata: mockDiscoverServerTools,
   },
 }))
 
@@ -57,6 +57,7 @@ const initialServer = {
   connectionStatus: 'connected',
   lastError: null,
   lastConnected: new Date('2026-01-01T00:00:00.000Z'),
+  lastToolsRefresh: new Date('2026-01-01T00:00:00.000Z'),
   toolCount: 4,
   statusConfig: { consecutiveFailures: 0, lastSuccessfulDiscovery: null },
 }
@@ -139,6 +140,7 @@ describe('MCP server refresh route', () => {
     const newerSuccessfulServer = {
       ...initialServer,
       lastConnected: new Date(Date.now() + 60_000),
+      lastToolsRefresh: new Date(Date.now() + 60_000),
       toolCount: 7,
     }
     mockSelect.mockReturnValueOnce(selectRows([newerSuccessfulServer]))
@@ -161,15 +163,18 @@ describe('MCP server refresh route', () => {
   })
 
   it('does not 500 when workflow sync fails after a successful discovery', async () => {
-    mockDiscoverServerTools.mockResolvedValueOnce([
-      {
-        name: 'search',
-        description: 'Search tool',
-        inputSchema: {},
-        serverId: 'server-1',
-        serverName: 'OAuth Server',
-      },
-    ])
+    mockDiscoverServerTools.mockResolvedValueOnce({
+      tools: [
+        {
+          name: 'search',
+          description: 'Search tool',
+          inputSchema: {},
+          serverId: 'server-1',
+          serverName: 'OAuth Server',
+        },
+      ],
+      state: 'published',
+    })
     // The route's server lookup consumes the first select (beforeEach). The sync's
     // workflow select is left unmocked, so it throws — exercising the guard that
     // keeps a secondary sync failure from turning a successful refresh into a 500.
@@ -190,4 +195,34 @@ describe('MCP server refresh route', () => {
       })
     )
   })
+
+  it('reports live tools when cache degradation prevents status publication', async () => {
+    mockDiscoverServerTools.mockResolvedValueOnce({
+      tools: [
+        {
+          name: 'search',
+          description: 'Search tool',
+          inputSchema: {},
+          serverId: 'server-1',
+          serverName: 'OAuth Server',
+        },
+      ],
+      state: 'unavailable',
+    })
+    mockSelect.mockReturnValueOnce(selectRows([persistedServer]))
+
+    const request = new Request('http://localhost/api/mcp/servers/server-1/refresh', {
+      method: 'POST',
+    }) as NextRequest
+    const response = await POST(request, { params: Promise.resolve({ id: 'server-1' }) })
+    const body = await response.json()
+
+    expect(body.data).toEqual(
+      expect.objectContaining({
+        status: 'connected',
+        error: null,
+        toolCount: 1,
+      })
+    )
+  })
 })

apps/sim/app/api/mcp/servers/[id]/refresh/route.ts

@@ -9,7 +9,7 @@ import { mcpServerIdParamsSchema } from '@/lib/api/contracts/mcp'
 import { validationErrorResponse } from '@/lib/api/server'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { withMcpAuth } from '@/lib/mcp/middleware'
-import { mcpService } from '@/lib/mcp/service'
+import { type McpServerDiscoveryState, mcpService } from '@/lib/mcp/service'
 import type { McpTool, McpToolSchema } from '@/lib/mcp/types'
 import {
   categorizeError,
@@ -188,16 +188,18 @@ export const POST = withRouteHandler(
 
         let syncResult: SyncResult = { updatedCount: 0, updatedWorkflowIds: [] }
         let discoveredTools: McpTool[] = []
+        let discoveryState: McpServerDiscoveryState | null = null
         let discoveryError: string | null = null
-        const discoveryStartedAt = new Date()
 
         try {
-          discoveredTools = await mcpService.discoverServerTools(
+          const discovery = await mcpService.discoverServerToolsWithMetadata(
             userId,
             serverId,
             workspaceId,
             true
           )
+          discoveredTools = discovery.tools
+          discoveryState = discovery.state
           logger.info(
             `[${requestId}] Discovered ${discoveredTools.length} tools from server ${serverId}`
           )
@@ -214,6 +216,7 @@ export const POST = withRouteHandler(
             url: mcpServers.url,
             connectionStatus: mcpServers.connectionStatus,
             lastConnected: mcpServers.lastConnected,
+            lastToolsRefresh: mcpServers.lastToolsRefresh,
             lastError: mcpServers.lastError,
             toolCount: mcpServers.toolCount,
           })
@@ -253,10 +256,20 @@ export const POST = withRouteHandler(
         let lastError = refreshedServer ? refreshedServer.lastError : discoveryError
         let toolCount = refreshedServer?.toolCount ?? discoveredTools.length
 
+        if (
+          discoveryError === null &&
+          (discoveryState === 'unavailable' || discoveryState === 'winner-cache')
+        ) {
+          connectionStatus = 'connected'
+          lastError = null
+          toolCount = discoveredTools.length
+        }
+
         if (discoveryError !== null && connectionStatus === 'connected') {
           const newerSuccessWonRace =
-            refreshedServer?.lastConnected != null &&
-            refreshedServer.lastConnected > discoveryStartedAt
+            refreshedServer?.lastToolsRefresh != null &&
+            (server.lastToolsRefresh == null ||
+              refreshedServer.lastToolsRefresh > server.lastToolsRefresh)
 
           if (!newerSuccessWonRace) {
             connectionStatus = 'disconnected'

apps/sim/lib/mcp/service.test.ts

@@ -548,15 +548,18 @@ describe('McpService.discoverTools per-server caching', () => {
       )
       .mockResolvedValueOnce([tool('new-tool', 'mcp-a')])
 
-    const older = mcpService.discoverServerTools(USER_ID, 'mcp-a', WORKSPACE_ID, false)
+    const older = mcpService.discoverServerToolsWithMetadata(USER_ID, 'mcp-a', WORKSPACE_ID, false)
     await vi.waitFor(() => expect(mockListTools).toHaveBeenCalledTimes(1))
 
     mockCacheAdapter.beginMutation.mockRejectedValueOnce(new Error('transient ordering failure'))
     const newer = mcpService.discoverServerTools(USER_ID, 'mcp-a', WORKSPACE_ID, true)
     await expect(newer).resolves.toEqual([tool('new-tool', 'mcp-a')])
 
     resolveOlder?.([tool('old-tool', 'mcp-a')])
-    await expect(older).resolves.toEqual([tool('new-tool', 'mcp-a')])
+    await expect(older).resolves.toEqual({
+      tools: [tool('new-tool', 'mcp-a')],
+      state: 'winner-cache',
+    })
 
     expect(mockCacheAdapter.beginMutation).toHaveBeenCalledTimes(3)
     expect(cacheStore.get(serverKey)?.tools).toEqual([tool('new-tool', 'mcp-a')])
@@ -632,8 +635,11 @@ describe('McpService.discoverTools per-server caching', () => {
     mockCacheAdapter.beginMutation
       .mockRejectedValueOnce(new Error('ordering unavailable'))
       .mockRejectedValueOnce(new Error('ordering unavailable'))
-    const newer = mcpService.discoverServerTools(USER_ID, 'mcp-a', WORKSPACE_ID, true)
-    await expect(newer).resolves.toEqual([tool('unowned-new-tool', 'mcp-a')])
+    const newer = mcpService.discoverServerToolsWithMetadata(USER_ID, 'mcp-a', WORKSPACE_ID, true)
+    await expect(newer).resolves.toEqual({
+      tools: [tool('unowned-new-tool', 'mcp-a')],
+      state: 'unavailable',
+    })
 
     resolveOlder?.([tool('owned-old-tool', 'mcp-a')])
     await expect(older).resolves.toEqual([tool('owned-old-tool', 'mcp-a')])

apps/sim/lib/mcp/service.ts

@@ -72,6 +72,18 @@ const STATUS_UPDATE_CAS_ATTEMPTS = 3
 type CacheMutationResult = 'applied' | 'superseded' | 'unavailable'
 type SuccessfulPublicationResult = 'published' | Exclude<CacheMutationResult, 'applied'>
 
+export type McpServerDiscoveryState =
+  | 'cached'
+  | 'published'
+  | 'winner-cache'
+  | 'superseded'
+  | 'unavailable'
+
+export interface McpServerDiscoveryResult {
+  tools: McpTool[]
+  state: McpServerDiscoveryState
+}
+
 type DiscoveryOutcome =
   | { kind: 'cached'; tools: McpTool[] }
   | {
@@ -188,7 +200,7 @@ class McpService {
   private readonly cacheTimeout = MCP_CONSTANTS.CACHE_TIMEOUT
   private unsubscribeConnectionManager?: () => void
   // Keyed on (workspaceId, serverId, userId) — OAuth-scoped tokens vary per user.
-  private inflightServerDiscovery = new Map<string, Promise<McpTool[]>>()
+  private inflightServerDiscovery = new Map<string, Promise<McpServerDiscoveryResult>>()
 
   constructor() {
     this.cacheAdapter = createMcpCacheAdapter()
@@ -942,6 +954,16 @@ class McpService {
     workspaceId: string,
     forceRefresh = false
   ): Promise<McpTool[]> {
+    return (await this.discoverServerToolsWithMetadata(userId, serverId, workspaceId, forceRefresh))
+      .tools
+  }
+
+  async discoverServerToolsWithMetadata(
+    userId: string,
+    serverId: string,
+    workspaceId: string,
+    forceRefresh = false
+  ): Promise<McpServerDiscoveryResult> {
     const inflightKey = `${workspaceId}:${serverId}:${userId}:${forceRefresh ? 'force' : 'cache'}`
     const existing = this.inflightServerDiscovery.get(inflightKey)
     if (existing) return existing
@@ -963,7 +985,7 @@ class McpService {
     serverId: string,
     workspaceId: string,
     forceRefresh: boolean
-  ): Promise<McpTool[]> {
+  ): Promise<McpServerDiscoveryResult> {
     const requestId = generateRequestId()
     const maxRetries = 2
 
@@ -972,7 +994,7 @@ class McpService {
         const cached = await this.cacheAdapter.get(serverCacheKey(workspaceId, serverId))
         if (cached) {
           logger.debug(`[${requestId}] Cache hit for server ${serverId}`)
-          return cached.tools
+          return { tools: cached.tools, state: 'cached' }
         }
       } catch (error) {
         logger.warn(`[${requestId}] Cache read failed for server ${serverId}:`, error)
@@ -1021,10 +1043,14 @@ class McpService {
               reason: publication,
             })
             if (publication === 'superseded') {
-              return (await this.getCurrentCachedTools(workspaceId, serverId)) ?? []
+              const winner = await this.getCurrentCachedTools(workspaceId, serverId)
+              return winner
+                ? { tools: winner, state: 'winner-cache' }
+                : { tools: [], state: 'superseded' }
             }
+            return { tools, state: 'unavailable' }
           }
-          return tools
+          return { tools, state: 'published' }
         } finally {
           await client.disconnect()
         }