1# MCP Tool (Model Context Protocol)
2 
3Connect agents to remote MCP servers to extend capabilities with external tools and data sources. MCP is an open standard for LLM tool integration.
4 
5## Prerequisites
6 
7- A remote MCP server endpoint (e.g., `https://api.githubcopilot.com/mcp`)
8- For authenticated servers: a [project connection](../../../project/connections.md) storing credentials
9- RBAC: **Contributor** or **Owner** role on the Foundry project
10 
11## Authenticated Server Connections
12 
13For authenticated MCP servers, create an `api_key` project connection to store credentials. Unauthenticated servers (public endpoints) don't need a connection — omit `project_connection_id`.
14 
15See [Project Connections](../../../project/connections.md) for connection management via Foundry MCP tools.
16 
17## MCPTool Parameters
18 
19| Parameter | Required | Description |
20|-----------|----------|-------------|
21| `server_label` | Yes | Unique label for this MCP server within the agent |
22| `server_url` | Yes | Remote MCP server endpoint URL |
23| `require_approval` | No | `"always"` (default), `"never"`, or `{"never": ["tool1"]}` / `{"always": ["tool1"]}` |
24| `allowed_tools` | No | List of specific tools to enable (default: all) |
25| `project_connection_id` | No | Connection ID for authenticated servers |
26 
27## Approval Workflow
28 
291. Agent sends request → MCP server returns tool calls
302. Response contains `mcp_approval_request` items
313. Your code reviews tool name + arguments
324. Submit `McpApprovalResponse` with `approve=True/False`
335. Agent completes work using approved tool results
34 
35> **Best practice:** Always use `require_approval="always"` unless you fully trust the MCP server. Use `allowed_tools` to restrict which tools the agent can access.
36 
37## Hosting Local MCP Servers
38 
39Agent Service only accepts **remote** MCP endpoints. To use a local server, deploy it to:
40 
41| Platform | Transport | Notes |
42|----------|-----------|-------|
43| [Azure Container Apps](https://github.com/Azure-Samples/mcp-container-ts) | HTTP POST/GET | Any language, container rebuild needed |
44| [Azure Functions](https://github.com/Azure-Samples/mcp-sdk-functions-hosting-python) | HTTP streamable | Python/Node/.NET/Java, key-based auth |
45 
46## Known Limitations
47 
48- **100-second timeout** for non-streaming MCP tool calls
49- **Identity passthrough not supported in Teams** — agents published to Teams use project managed identity
50- **Network-secured Foundry** can't use private MCP servers in same vNET — only public endpoints
51 
52## Troubleshooting
53 
54| Error | Cause | Fix |
55|-------|-------|-----|
56| `Invalid tool schema` | `anyOf`/`allOf` in MCP server definition | Update MCP server schema to use simple types |
57| `Unauthorized` / `Forbidden` | Wrong credentials in connection | Verify connection credentials match server requirements |
58| Model never calls MCP tool | Misconfigured server_label/url | Check `server_label`, `server_url`, `allowed_tools` values |
59| Agent stalls after approval | Missing `previous_response_id` | Include `previous_response_id` in follow-up request |
60| Timeout | Server takes >100s | Optimize server-side logic or break into smaller operations |
61 
62## References
63 
64- [MCP tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/mcp?view=foundry)
65- [Tool Catalog](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/tool-catalog?view=foundry)
66- [Project Connections](../../../project/connections.md)
67