Foundry Toolbox — Concept, API Shape & Schema
Understand
What a toolbox is
A toolbox is a managed Foundry resource: define a curated set of tools once, manage them centrally, and expose them through a single MCP-compatible endpoint any agent can consume. The platform handles credential injection, token refresh, and policy enforcement at runtime.
✅ Recommended: a toolbox is the best way to connect tools to a Foundry agent — it centralizes auth (bearer tokens, refresh, OAuth consent, per-user passthrough), enforces policy, and lets you reconfigure tools without changing agent code.
- Build — select tools, configure auth centrally, publish a reusable toolbox.
- Consume — connect any MCP-compatible runtime (Microsoft Agent Framework, LangGraph, GitHub Copilot, Claude Code, Copilot Studio, custom code).
For consuming from hosted-agent code, see use-toolbox-in-hosted-agent.md.
Build & use
Create & use a toolbox (happy path)
🚦 Before creating a toolbox/connection, read the boundary rules in create-hosted.md → Toolbox creation boundary.
Prerequisites
RBAC — the calling identity (you, and the agent identity at runtime) needs Foundry User on the project. Grant at project scope if missing.
CLI extension — install once:
azd extension install azure.ai.toolboxes
The flow
Using the azd ai CLI:
- Create the connection (
azd ai connection create ...). - Create the toolbox (
azd ai toolbox create) or add to an existing one (azd ai toolbox connection add). - If you added to an existing toolbox, promote the new version (
azd ai toolbox publish <name> <version>) —createauto-publishes its first version; later mutations don't (see Versions). - Read the endpoint (
azd ai toolbox show <name> --output json). azd env set TOOLBOX_ENDPOINT "<endpoint>".- Reference it in the agent service's
environmentVariablesinazure.yaml. azd deploy.
Each tool type has its own flow — pick your tool in Supported tool types and follow its Setup guide. Full CLI surface: toolbox-azd.md.
Supported tool types
The tool type values supported inside a toolbox version. mcp's first four auth modes work for any MCP server; the last two are catalog-only (Foundry pre-wires the app/broker).
type |
Tool | authType |
Connection? | Setup guide |
|---|---|---|---|---|
mcp |
Remote MCP server — no auth (public) | None |
No | tool-mcp-noauth.md |
mcp |
Remote MCP server — static key | CustomKeys |
Yes (key connection) | tool-mcp-key-auth.md |
mcp |
Remote MCP server — OAuth, custom app (BYO); runs as the user | OAuth2 |
Yes (client_id / client_secret + reply URL) |
tool-mcp-custom-oauth.md |
mcp |
Remote MCP server — agent identity / project MI; runs as the agent | AgenticIdentityToken / ProjectManagedIdentity |
Yes (audience + RBAC on the target) |
tool-mcp-agent-identity.md |
mcp |
Catalog only — OAuth, Foundry-managed connector; consent once, no BYO app | OAuth2 (Foundry-owned) |
No (Foundry brokers it) | tool-mcp-managed-oauth.md; foundry-tool-catalog.md |
mcp |
Catalog only — Microsoft first-party pass-through; caller's identity forwarded, no consent | UserEntraToken |
Yes (via --audience) |
tool-mcp-user-entra-token.md; foundry-tool-catalog.md |
openapi |
REST API via an OpenAPI 3.x spec | — | Conditional (connection needs project_connection_id; managed_identity uses project MI + audience) |
tool-openapi.md |
a2a_preview |
Call another Foundry agent as a tool | — | Optional | tool-a2a.md |
web_search |
Web search (basic Bing; custom_search_configuration for Custom Search) |
— | No (basic); Yes for Custom Search | tool-web-search.md |
azure_ai_search |
Azure AI Search index | — | Yes (Search service connection) | tool-azure-ai-search.md |
code_interpreter |
Sandboxed Python execution | — | No | tool-code-interpreter.md |
file_search |
Vector-store retrieval over uploaded files | — | No (part of the toolbox) | tool-file-search.md |
fabric_iq_preview |
Microsoft Fabric data | — | Yes (Fabric IQ OAuth; tenant admin consent) | tool-fabric-iq.md |
browser_automation_preview |
Browser automation | — | Yes (PlaywrightWorkspace connection) |
tool-browser-automation.md |
toolbox_search_preview |
Tool Search — swaps tools/list for tool_search + call_tool meta-tools |
— | No | tool-tool-search.md |
Work IQ is a common Microsoft 365 MCP server with its own guide: tool-work-iq.md.
Adjacent (not a toolbox type):
- Agent Memory — configured at the project level, separate from the toolbox. See Memory docs.
- Routines (preview) — an agent trigger (
schedule/timer/github_issue/custom). See Routines docs.
Composition rules (multiple tools in one toolbox)
At most one tool may be unnamed; name every other. See toolbox-azd.md § Multi-tool rule.
Enable Tool Search
Before adding more than ~5 tools, add { "type": "toolbox_search_preview" }. This replaces the full tools/list with two meta-tools — tool_search and call_tool — so context cost stays flat. Full behavior: tool-tool-search.md, Tool Search docs.
Versioning, endpoints & MCP protocol
Versions
- Versions are immutable snapshots — every change produces a new version.
- The default version is what the consumer endpoint serves.
- The first version is auto-promoted; later ones must be promoted explicitly.
MCP endpoint URL format
| Role | Endpoint | Use |
|---|---|---|
| Consumer | {project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1 |
Connect agents; always serves default_version. |
| Developer | {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1 |
Test a version before promoting. |
?api-version=v1 is required; auth is a bearer token scoped https://ai.azure.com/.default. See mcp-protocol.md § Endpoint URL details.
MCP protocol, testing & troubleshooting
Toolboxes speak MCP (JSON-RPC 2.0 over HTTP POST). For protocol methods, tool naming, endpoint testing, and troubleshooting, see mcp-protocol.md and test-endpoint.md.