🪟 fix: Surface MCP Initialization Errors (#14529)

api/server/routes/__tests__/mcp.spec.js

@@ -1885,6 +1885,37 @@ describe('MCP Routes', () => {
       });
     });
 
+    it('should return structured reinitialization failure details', async () => {
+      const mockMcpManager = {
+        disconnectUserConnection: jest.fn().mockResolvedValue(),
+      };
+
+      mockRegistryInstance.getServerConfig.mockResolvedValue({});
+      require('~/config').getMCPManager.mockReturnValue(mockMcpManager);
+      require('~/server/services/Tools/mcp').reinitMCPServer.mockResolvedValue({
+        success: false,
+        message: "MCP server 'test-server' requires user-provided variables",
+        serverName: 'test-server',
+        oauthRequired: false,
+        oauthUrl: null,
+        failureReason: 'missing_custom_user_vars',
+        missingUserVars: ['API_KEY'],
+      });
+
+      const response = await request(app).post('/api/mcp/test-server/reinitialize');
+
+      expect(response.status).toBe(200);
+      expect(response.body).toEqual({
+        success: false,
+        message: "MCP server 'test-server' requires user-provided variables",
+        serverName: 'test-server',
+        oauthRequired: false,
+        oauthUrl: null,
+        failureReason: 'missing_custom_user_vars',
+        missingUserVars: ['API_KEY'],
+      });
+    });
+
     it('should return 500 when reinitialize fails with non-OAuth error', async () => {
       const mockMcpManager = {
         disconnectUserConnection: jest.fn().mockResolvedValue(),

api/server/routes/mcp.js

@@ -718,7 +718,15 @@ router.post(
         return res.status(500).json({ error: 'Failed to reinitialize MCP server for user' });
       }
 
-      const { success, message, oauthRequired, oauthUrl, connectionDeferred } = result;
+      const {
+        success,
+        message,
+        oauthRequired,
+        oauthUrl,
+        failureReason,
+        missingUserVars,
+        connectionDeferred,
+      } = result;
 
       if (oauthRequired) {
         const flowId = getOAuthFlowId(user.id, serverName);
@@ -731,6 +739,8 @@ router.post(
         oauthUrl,
         serverName,
         oauthRequired,
+        failureReason,
+        missingUserVars,
         connectionDeferred,
       });
     } catch (error) {