--- schema_version: "1" id: 66f432e2f187bb7386fad155ced722e5b295c8c929aeb2cdc76ae6d540b34908 title: MCP for Agentforce Troubleshooting collection: admin version: current locale: en-us portal_url: https://docs.salesforce.com/admin/current/en-us/ai/264-0-0/agent_mcp_troubleshoot.md canonical_url: https://help.salesforce.com/s/articleView?id=ai.agent_mcp_troubleshoot.htm&release=264.0.0&type=5 source_site: help.salesforce.com content_type: documentation content_hash: 0a1012b6fe616422289b94d86364cb5ba14d7d85da41873ddf4c3b7a35d57112 description: Solve common issues with Agentforce solutions that integrate with MCP for Agentforce. products: - Agentforce - Cross Cloud release: "264" --- # MCP for Agentforce Troubleshooting Solve common issues with Agentforce solutions that integrate with MCP for Agentforce. ## My agent can't find an MCP server. No response from a Salesforce-registered MCP server. - Check the network connection. - Verify that the MCP server is up and running correctly. - Check your MCP server registration settings. Has something changed on the server side, such as its URL? Is the tool still available on the MCP server? Update registration settings as needed. See [Edit MCP Server Details](https://help.salesforce.com/s/articleView?id=ai.agent_mcp_registration_manage_edit.htm&release=264.0.0&type=5 "You can edit a server’s description. If your server uses OAuth 2.0, you can edit the identity provider URL, scope, client ID, and client secret. The server name, server URL, and authentication method aren’t editable."). - For Salesforce-hosted MCP servers, see also [Server Connection Failures](https://developer.salesforce.com/docs/platform/hosted-mcp-servers/guide/connection-issues.html). Resolve any issues and try connecting to the server again. ## My agent can't access an MCP server tool (authentication error). Authentication errors can result from incorrect or expired credentials, or other server-side changes. MCP for Agentforce supports these types: - no authentication - OAuth 2.0 client credential - External credential with a supported authentication protocol (see [Register a Third-Party MCP Server in Agentforce Registry](https://help.salesforce.com/s/articleView?id=ai.agent_mcp_connect_register.htm&release=264.0.0&type=5 "Create a connection to a third-party MCP server. Allowlist the server tools that you want to use with your agents.")) Check your authentication settings for the Salesforce-registered MCP server. Do you need to renew your credentials? Has something else changed on the server side? For example, does the server now require authentication credentials when it previously didn't? Update your authentication settings accordingly. See [Edit MCP Server Details](https://help.salesforce.com/s/articleView?id=ai.agent_mcp_registration_manage_edit.htm&release=264.0.0&type=5 "You can edit a server’s description. If your server uses OAuth 2.0, you can edit the identity provider URL, scope, client ID, and client secret. The server name, server URL, and authentication method aren’t editable."). For Salesforce-hosted MCP servers, see also [Authentication Issues](https://developer.salesforce.com/docs/platform/hosted-mcp-servers/guide/authentication-issues.html). ## My agent is getting an out-of-sync error. Server-side changes in Salesforce-registered MCP servers can cause your current registration and allowlist settings to be out of sync. For example, updates to a server tool (such as a changed description, differences in input or output schema, or even the tool's removal) can adversely affect agents that depend on that tool. MCP for Agentforce identifies such issues, flags a registered MCP server or server tool as Out of Sync, and notifies an admin. See [Resolve Out-of-Sync MCP Server Issues](https://help.salesforce.com/s/articleView?id=ai.agent_mcp_registration_manage_update.htm&release=264.0.0&type=5 "MCP server providers own their servers and can change server and tool settings at any time. Server-side changes make your current registration settings out of sync, which can adversely affect agents that rely on MCP server tools. Agentforce identifies the issue, flags a registered MCP server or tool as Out of Sync, and notifies an admin. Resolve the issue by following the applicable steps."). ## My agent is getting an MCP time out error. MCP-related timeouts errors occur when: - a Salesforce-registered MCP server tool is unavailable or takes longer than 60 seconds to respond - multiple servers are called and collectively take longer than 120 seconds to respond (Atlas reasoning engine timeout) Start by determining whether high latency is due to MCP-related operations. Use debugging tools described in "Troubleshooting Resources" (such as the Plan Tracer in Agent Builder and trace logs) to isolate where timeouts occur in your Agentforce solution. If you've confirmed that MCP operations are causing timeout errors: - Check the network connection. - Verify that the MCP server is up and running correctly. - For Salesforce-hosted MCP servers, use administrative tools to troubleshoot delays caused by MCP-related operations. (Visibility into third-party MCP servers is limited.) Resolve any issues, test and deploy your fixes, and continue monitoring for timeouts. ## My agent is having other MCP-related issues. - Ensure that your Agentforce solution complies with [Requirements for MCP for Agentforce](https://help.salesforce.com/s/articleView?id=ai.agent_mcp_requirements.htm&release=264.0.0&type=5 "Review the requirements to make sure you’re ready to register and use MCP servers in Agentforce."). - Review [Considerations for MCP for Agentforce](https://help.salesforce.com/s/articleView?id=ai.agent_mcp_considerations.htm&release=264.0.0&type=5 "Carefully review the current considerations and limitations for MCP for Agentforce.") to determine whether applicable changes are required for your Agentforce solution. - Contact Salesforce Support through your organization’s support channels. ## Troubleshooting Resources Agentforce provides tools and features that help you identify patterns, investigate root causes, and take corrective action. - In Agent Builder, use the Plan Tracer in the Conversation Preview Panel to isolate network traffic errors between the client and the MCP server. Inspect the detailed, step-by-step decisions and actions your agent takes during a conversation or workflow test. Focus on MCP-related operations. - Use [enhanced event logs](https://help.salesforce.com/s/articleView?id=ai.copilot_setup_enhanced_event_logs.htm&release=264.0.0&type=5 "Event logs capture the events and user messages in an agent session to help you test and troubleshoot your agent. In supported agent types, enable enhanced event logs to store conversation data and view all session activity in one place. When enhanced event logs aren't enabled, events associated with agent and user messages (such as Message sent: and User response:) are logged, but the messages themselves aren't included in the event.") to provide granular details about agent conversations. - Use [Agent Analytics](https://help.salesforce.com/s/articleView?id=ai.generative_ai_agent_analytics.htm&release=264.0.0&type=5 "Analyze your AI agents’ performance within user and agent sessions. Agent Analytics is built on the unified Session Tracing Data Model (STDM), which captures every event and interaction within a session and logs it as individual events. You can query the logged ‌events to gain insights and optimize the Agent.") to monitor agent performance and detect error trends. Investigate patterns and root causes at the session level (see [Analyze Data with Agent Optimization](https://help.salesforce.com/s/articleView?id=ai.generative_ai_optimize_use.htm&release=264.0.0&type=5 "Use Agent Optimization to drill into sessions, analyze quality scores, and identify patterns to improve your agent's performance.")). - In [Agent Health Monitoring](https://help.salesforce.com/s/articleView?id=ai.agent_monitor_health.htm&release=264.0.0&type=5 "Agent Health Monitoring detects and notifies you of silent agent failures—like spiking error rates or high latency—in near-real time across your AI agents. Rapidly respond to agent performance issues to mitigate customer impact."), set alert thresholds to trigger notifications when agent performance breaches threshold levels. - For Salesforce-hosted MCP servers, diagnose and remedy issues by using the administrative tools that accompany the MCP server.