Stale MCP tools are persisted in agents (Infinite reconnect)

[AaronPowell96]

What happened?

When you connect an MCP to an agent and select tools, these tools are stored against the agent.
If you modify tool names or remove tools and redeploy the MCP, the agent will still reference these stale tools even when they no longer exist and they have correctly been removed from the Agent MCP Tools UI so you can no longer deselect them to prevent this issue.

When MCP servers are redeployed with different tool sets (tools added/removed), LibreChat agents experience infinite reconnection loops and never complete tool execution. The agent shows "establishing connection..." repeatedly without resolving.

The issue stems from stale tool references being passed to agents from the cached tool definitions:

1. Agent loads tools → loadAgentTools() retrieves cached tools and adds all MCP tools matching the requested server names to the agent's tool list
2. Stale tools included → Cache contains references to tools that no longer exist on the redeployed server
3. Agent attempts to use missing tool → createMCPTool() can't find the tool definition and triggers reconnectServer()
4. Reconnection clears cache → New tools are fetched, but agent still has stale tool references from initial load
5. Infinite loop → Next tool execution repeats the cycle with the same stale tool references

The problem occurs in loadAgentTools() where tools are filtered from cached definitions:

// chat/LibreChat/api/server/services/ToolService.js:83-92
for (const toolName of Object.keys(availableTools)) {
  if (!toolName.includes(mcp_delimiter)) {
    continue;
  }
  const mcpServer = toolName.split(mcp_delimiter)?.[1];
  if (mcpServer && mcpServers.has(mcpServer)) {
    addedServers.add(mcpServer);
    tools.push(toolName); // ← Stale tools get added here
  }
}

Solution? Filter Out Stale MCP Tools During Agent Loading

Added validation in loadAgentTools() to check if MCP tools actually exist in the current cached tools before including them in the agent's tool list:

// Get current available tools to filter out stale MCP tool references
const availableTools = await getCachedTools({ userId: req.user?.id, includeGlobal: true });
const staleMCPTools = [];

const _agentTools = agent.tools?.filter((tool) => {
  // ... existing filters for file_search, execute_code, web_search ...

  // Check if this is an MCP tool that no longer exists
  if (tool.includes(Constants.mcp_delimiter)) {
    if (!availableTools || !availableTools[tool]) {
      staleMCPTools.push(tool);
      return false; // Filter out stale MCP tools
    }
  }

  return true;
});

// Log any stale MCP tools that were filtered out
if (staleMCPTools.length > 0) {
  logger.warn(
    `[Agent ${agent.id}] Filtered out ${staleMCPTools.length} stale MCP tools: ${staleMCPTools.join(', ')}`,
  );
}

This focused solution prevents stale tool references from reaching the agent execution layer, eliminating the reconnection loops while preserving tool persistence and requiring no breaking changes.

However, note that this change does not remove the tools from the agents tool list in the DB which means if the tool is added back to the MCP it will be available again in the agent.

Version Information

b85950a

Steps to Reproduce

1. Deploy MCP with tools
2. Add MCP to an agent and select a tool
3. Rename MCP tool and redeploy
4. Chat to Agent (reinitialise could fail or just try to call the stale tool)
5. Reauth the MCP server yourself, see the tool disappear from the Agent tools options but the new one doesn't appear.
6. Agent still thinks it can call old tool.

What browsers are you seeing the problem on?

No response

Relevant log output

2025-09-23 12:02:02 [33m[3mwarn[23m[39m: [33m[3m[MCP][myMCPName][get_company_integration_features] Tool definition not found, cannot create tool.[23m[39m
2025-09-23 12:02:02 [33m[3mwarn[23m[39m: [33m[3m[MCP][myMCPName][find_companies_by_integration] Requested tool not found in available tools, re-initializing MCP server.[23m[39m
2025-09-23 12:02:02 [32minfo[39m: [32m[MCP][User: 68c190f9e9241b87e5278fb5][myMCPName] Establishing new connection[39m
2025-09-23 12:02:04 [32minfo[39m: [32m[MCP][User: 68c190f9e9241b87e5278fb5][myMCPName] Creating streamable-http transport: https://myMCPName.myDomain.com/mcp[39m
2025-09-23 12:02:04 [31merror[39m: [31m[MCP][User: 68c190f9e9241b87e5278fb5][myMCPName] Transport error: Error POSTing to endpoint (HTTP 401): {"error": "invalid_token", "error_description": "Authentication required"}[39m
2025-09-23 12:02:04 [32minfo[39m: [32m[MCP][User: 68c190f9e9241b87e5278fb5][myMCPName] Streamable-http transport closed[39m
2025-09-23 12:02:04 [33m[3mwarn[23m[39m: [33m[3m[MCP][User: 68c190f9e9241b87e5278fb5][myMCPName] OAuth authentication required[23m[39m
2025-09-23 12:02:04 [32minfo[39m: [32m[MCP][myMCPName][68c190f9e9241b87e5278fb5] oauthRequired event received[39m
2025-09-23 12:02:04 [32minfo[39m: [32m[MCP][myMCPName][68c190f9e9241b87e5278fb5] OAuth flow started, issued authorization URL to user[39m
2025-09-23 12:02:07 [32minfo[39m: [32m[MCP][myMCPName][68c190f9e9241b87e5278fb5] OAuth flow completed, tokens received for myMCPName[39m
2025-09-23 12:02:07 [32minfo[39m: [32m[MCP][myMCPName][68c190f9e9241b87e5278fb5] OAuth tokens saved to storage[39m
2025-09-23 12:02:07 [32minfo[39m: [32m[MCP][User: 68c190f9e9241b87e5278fb5][myMCPName] OAuth handled successfully, connection will be retried[39m
2025-09-23 12:02:07 [31merror[39m: [31m[MCP][User: 68c190f9e9241b87e5278fb5][myMCPName] Connection failed: Connection not established[39m
2025-09-23 12:02:09 [32minfo[39m: [32m[MCP][User: 68c190f9e9241b87e5278fb5][myMCPName] Creating streamable-http transport: https://myMCPName.myDomain.com/mcp[39m
2025-09-23 12:02:09 [32minfo[39m: [32m[MCP][User: 68c190f9e9241b87e5278fb5][myMCPName] Connection successfully established[39m
2025-09-23 12:02:09 [32minfo[39m: [32m[MCP Reinitialize] Successfully established connection for myMCPName[39m
2025-09-23 12:02:09 [33m[3mwarn[23m[39m: [33m[3m[MCP][myMCPName][find_companies_by_integration] Tool still not found after reconnection - tool may have been removed from server[23m[39m
2025-09-23 12:02:09 [33m[3mwarn[23m[39m: [33m[3m[MCP][myMCPName][find_companies_by_integration] Tool definition not found, cannot create tool.[23m[39m
2025-09-23 12:02:09 [33m[3mwarn[23m[39m: [33m[3m[MCP][myMCPName][find_companies_by_property] Requested tool not found in available tools, re-initializing MCP server.[23m[39m
2025-09-23 12:02:09 [32minfo[39m: [32m[MCP][User: 68c190f9e9241b87e5278fb5][myMCPName] Establishing new connection[39m

Screenshots

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[danny-avila]

The code examples and relevant PR do not reference the latest code-base changes. Please try reproducing the behavior on latest head of main branch. If there's still an issue, feel free to re-submit and issue and relevant PR.

[danny-avila]

Also, this should be considered for the tool list changing: #7117

[bhooshanvarma]

Does this still happen on your current build? The part I would isolate is whether removing the tool in the UI also removes its persisted agent reference. A stub tool renamed between two deployments should show that without involving a real backend.