MCP for Agentforce Troubleshooting

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.
• For Salesforce-hosted MCP servers, see also Server Connection Failures.

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

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.

For Salesforce-hosted MCP servers, see also Authentication Issues.

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.

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.
• Review Considerations 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 to provide granular details about agent conversations.
• Use Agent Analytics to monitor agent performance and detect error trends. Investigate patterns and root causes at the session level (see Analyze Data with Agent Optimization).
• In Agent Health Monitoring, 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.