Integrating custom tools into the Microsoft Copilot ecosystem can sometimes lead to unexpected errors. One such issue occurs when running the Azure AI Foundry Agent Service with a custom MCP (Microsoft Copilot Platform) Server: an error message that simply states — “Sorry, something went wrong.”

This blog discusses a scenario documented by Simon Doy, a Microsoft 365 and Azure developer, whose Azure AI Foundry Agent Service failed on one MCP Tool from his custom setup while others worked without issue. After investigation, the root cause was the presence of a friendly name property on the MCP Tool definition. Removing the friendly name resolved the failure, highlighting an important detail for developers working with custom MCP Servers.

Key Observations

• The failure affected only the tool that had a friendly name property; tools without friendly names on the same MCP Server worked correctly.
• The Agent Service returns a vague error: {'code': 'server_error', 'message': 'Sorry, something went wrong.'}, which complicates troubleshooting.
• Removing the friendly name property from the MCP Tool definition allowed the tool to work as expected.

Understanding the Issue

MCP Tools define capabilities that AI agents invoke. Each tool includes metadata such as an internal name and optionally a friendly name for display. In this case, the Azure AI Foundry Agent Service does not accept MCP Tools that include a friendly name property, causing the service to fail during tool loading.

Troubleshooting Approach

Simon Doy's method involved:

• Confirming other tools on the MCP Server worked.
• Isolating the problematic tool.
• Removing the friendly name property to verify it as the cause.

Due to minimal diagnostics from the Agent Service, this trial-and-error approach was necessary.

Recommendations

1. Avoid including a friendly name property in MCP Tool definitions when using Azure AI Foundry Agent Service.
2. Test each MCP Tool individually during development to catch such issues early.
3. Use internal names as the primary identifier for tools.
4. Monitor official updates and community resources for changes in MCP Server and Agent Service behavior.

Conclusion

This issue underscores the importance of careful metadata definition when building MCP Tools for Azure AI Foundry. The vague error message can be misleading, but removing friendly names from MCP Tools is a simple workaround to avoid failures.

Reference

Azure AI Foundry Agent Service Fails with MCP Tool — Original blog post by Simon Doy documenting this issue.