Setting the file. One moment.
Chapter 36 · Microsoft Foundry
Subchapter 36.79
foundry-agent/toolbox/references/mcp-protocol.mdMarkdown3 KBView on GitHub
{project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1. Always serves the default_version. Connect agents here so promoting a version needs no redeploy.{project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1. Test a specific version before promoting.?api-version=v1 is required — requests without it return HTTP 400.https://ai.azure.com/.default.Toolboxes use Model Context Protocol (MCP) — JSON-RPC 2.0 over HTTP POST:
initialize — optional handshake. tools/list / tools/call work without it. If you call it and the server returns an mcp-session-id header, resend it on subsequent calls.tools/list — returns all tools with names, descriptions, and input schemas.tools/call — invokes a tool and returns structured results. Plain POST works; SSE streaming is optional.
prompts/listis not supported. If your MCP client calls it automatically (e.g. MAF’sMCPStreamableHTTPTool), passload_prompts=False.
type: mcp) are exposed as {server_label}___{tool_name} — three underscores (e.g. myserver___get_info).name field, or the default tool name if unset.tool_search and call_tool.Each tool from tools/list includes a _meta.tool_configuration block with the type plus type-specific fields (e.g. server_label, server_url, require_approval for MCP).
Verify the MCP endpoint end-to-end with a bearer token + raw tools/list / tools/call — see test-endpoint.md.
| Symptom | Likely cause |
|---|---|
TOOLBOX_ENDPOINT not set | Run azd ai toolbox show + azd env set. |
| Env var missing in deployed agent | Add to the agent service’s environmentVariables in azure.yaml, azd deploy. |
403 Forbidden (incl. POST /toolboxes, connection PUT) | Caller lacks Foundry User (or Azure AI Developer) on the project — grant at project scope. |
400 Multiple tools without identifiers found | Two unnamed tools (or duplicate server_label) — keep at most one unnamed tool; name each other. See toolbox-azd.md § Multi-tool rule. |
tools/list returns zero | Version still provisioning, or tool type unavailable in region — wait ~10s, retry, or try another region. |
tools/list zero for MCP/A2A only | Invalid/missing connection creds — verify project_connection_id; for MI auth, check RBAC on the target. |
tools/list zero for OpenAPI only | Invalid OpenAPI spec — validate against 3.0/3.1; for MI auth, verify RBAC. |
For runtime/MCP-client errors (token scope, prompts/list, require_approval, tool-name prefixes), see use-toolbox-in-hosted-agent.md § Troubleshooting.