AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

microsoft-foundry

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent, managed harness agent, Copilot harness, voice agent, create/update/invoke/evaluate agent, add tool to agent, agent insights, batch/continuous eval, continuous monitoring, agent CI/CD, optimize/improve prompt, optimize agent instructions, Agent Optimizer, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure-prepare).

Original source
microsoft
License
MIT
Pinned revision
3f5b461b2314e01c400564051e92469114c5b68f

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read microsoft--microsoft-foundry at revision 3f5b461b2314e01c400564051e92469114c5b68f, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 151

foundry-agent/toolbox/references/mcp-protocol.md

Toolbox MCP protocol, tool naming & testing

Endpoint URL details

  • Consumer — {project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1. Always serves the default_version. Connect agents here so promoting a version needs no redeploy.
  • Developer — {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.
  • Auth: bearer token with scope https://ai.azure.com/.default.

MCP protocol

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/list is not supported. If your MCP client calls it automatically (e.g. MAF's MCPStreamableHTTPTool), pass load_prompts=False.

Tool naming

  • MCP-sourced tools (type: mcp) are exposed as {server_label}___{tool_name} — three underscores (e.g. myserver___get_info).
  • All other tool types use the entry's name field, or the default tool name if unset.
  • Tool Search injects two meta-tools named 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).

Testing the toolbox endpoint

Verify the MCP endpoint end-to-end with a bearer token + raw tools/list / tools/call — see test-endpoint.md.

Troubleshooting (create / provision)

| 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 on toolbox data-plane requests, including POST /toolboxes | Caller lacks Foundry User on the project — grant at project scope. | | 403 Forbidden on connection PUT | Caller lacks Foundry Project Manager (or Cognitive Services Contributor) 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.