Curate intent-based toolbox in Foundry (preview)

Use toolbox in Microsoft Foundry to add MCP servers, web search, Azure AI Search, file search, code interpreter tool and more to hosted agents through a single managed endpoint.

Items marked (preview) in this article are currently in public preview. This preview is provided without a service-level agreement, and we don’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

When you connect to non-Foundry tools, you might incur costs and data might be sent outside Foundry’s compliance boundary and processed according to the applicable terms and data handling policies. See the tool’s documentation to learn how to manage access to the tool.

A single agent can depend on multiple tools - APIs, Model Context Protocol (MCP) servers, connectors, and flows - each with its own authentication model and owning team. As you scale across an organization, teams re-implement the same tools independently, credentials get duplicated, governance becomes inconsistent, and there’s little visibility into what tools exist or who’s using them. Developers stall, not because the models aren’t capable, but because tool integration becomes the bottleneck.

Enterprises already have the infrastructure: gateways, credential vaults, policies, and observability. What’s been missing is a developer experience that packages this infrastructure into something reusable, discoverable, and governed by default.

Toolbox provides that experience. Define a curated set of tools once, manage them centrally in Foundry, and expose them through a single MCP-compatible endpoint that any agent can consume. The platform handles credential injection, token refresh, and enterprise policy enforcement at runtime.

Toolbox covers the full tool lifecycle through four pillars - Build and Consume are available today:

Pillar	Status	What it enables
Build	Available today	Select tools, configure authentication centrally, and publish a reusable toolbox that any team can consume.
Consume	Available today	Connect any agent to a single MCP-compatible endpoint to dynamically discover and invoke all tools in the toolbox.

:::image type=“content” source=”../../media/tools/toolbox/toolbox-architecture.png” alt-text=“Diagram showing Toolboxes in Foundry architecture: Build and Consume pillars consumed by LangGraph, Microsoft Agent Framework, GitHub Copilot, Claude Code, and Microsoft Copilot Studio, governed by default.” lightbox=”../../media/tools/toolbox/toolbox-architecture.png”:::

You create toolboxes in Foundry, but the consumption surface is open. Any MCP-compatible agent runtime or client can use a toolbox - including agents built with any framework, MCP-enabled IDEs, and custom code.

Because a toolbox is a managed resource, you can add, remove, or reconfigure tools without changing code in your agent. Your agent always connects to a single endpoint. Toolbox versioning gives you explicit control over when changes take effect - create and test a new version, then promote it to default when you’re ready. Every agent that points to the toolbox picks up the promoted version automatically, with no code changes and no redeployment.

In this article, you learn how to:

• Create a toolbox with one or more tools.
• Get the toolbox MCP endpoint.
• Verify that tools load correctly.
• Integrate a toolbox into your hosted agent.
• Manage toolbox versions and promote a version to default.
• Apply a guardrail (RAI policy) to a toolbox version.

For tool configuration syntax and authentication options for each tool type, see Configure tools.

Feature support

Feature	Python SDK	REST API	.NET SDK	JavaScript SDK	azd	Foundry Toolkit
Toolbox update, list, get, and delete	✔️	✔️	✔️	✔️	N/A	✔️
Toolbox version create	✔️	✔️	✔️	✔️	✔️	✔️
Toolbox version list, get, and delete	✔️	✔️	✔️	✔️	N/A	No. UI shows the latest version only.
MCP tool	✔️	✔️	✔️	✔️	✔️	✔️
Web Search tool	✔️	✔️	✔️	✔️	✔️	✔️
Azure AI Search tool	✔️	✔️	✔️	✔️	✔️	✔️
Code Interpreter tool	✔️	✔️	✔️	✔️	✔️	✔️
File Search tool	✔️	✔️	✔️	✔️	✔️	✔️
OpenAPI tool	✔️	✔️	✔️	✔️	✔️	No
Agent-to-Agent (A2A) tool	✔️	✔️	✔️	✔️	✔️	No
Fabric IQ tool	✔️	✔️	✔️	✔️	✔️	✔️
Guardrail (RAI policy)	✔️	✔️	✔️	✔️	✔️	✔️
Skill references	✔️	✔️	✔️	✔️	✔️	No
Tool Search tool	✔️	✔️	✔️	✔️	✔️	✔️
Work IQ tool	✔️	✔️	✔️	✔️	✔️	✔️
Browser Automation tool	✔️	✔️	✔️	✔️	✔️	No

Prerequisites

• An active Microsoft Foundry project.

• RBAC: Grant the Foundry User role on the Foundry project to each identity that applies to your scenario:

  • Developer (always required) — the identity that creates, updates, and manages toolbox versions.
  • Agent identity (required if using a hosted agent) — the agent’s managed identity that calls tools at runtime.
  • End user (required only for OAuth flows) — any user whose identity is proxied through OAuth or UserEntraToken connections (for example, OAuth-based MCP or user Entra token (managed user identity passthrough) flows).

• Your Foundry project needs to be at one of the supported regions. Individual tool types within a toolbox are further limited by region and model – not all tool types are available in every region or with every model. See Region and model compatibility.

• Visual Studio Code (VS Code).

• Install the Microsoft Foundry Toolkit for Visual Studio Code extension from the Visual Studio Code Marketplace.

• Python SDK: pip install azure-ai-projects azure-identity

• .NET SDK: dotnet add package Azure.AI.Projects --prerelease and dotnet add package Azure.Identity

• JavaScript SDK: npm install @azure/ai-projects @azure/identity

• Azure Developer CLI: Install the Azure Developer CLI (azd, 1.25 or later) and the unified Foundry CLI extension bundle:

  # If you previously installed individual extensions, uninstall them first.
  azd ext uninstall azure.ai.foundry
  
  # Install the unified bundle (provides azd ai agent, connection, inspector,
  # project, routine, skill, and toolbox).
  azd ext install azure.ai.foundry
  

• Every request to the toolbox MCP endpoint must include the header Foundry-Features: Toolboxes=V1Preview. Calls that omit this header fail. Include it in all HTTP clients, MCP transports, and SDK wrappers that call the toolbox endpoint.
• A toolbox supports at most one tool without a name field per tool type (Web Search, Azure AI Search, Code Interpreter, File Search). To include more than one instance of the same tool type, set a unique name on each instance to differentiate them. Including two instances of the same type without a name returns an invalid_payload error. For details, see Multiple tool types.
• Add a description to every tool in your toolbox to help the model select the right tool for each request.
• Carefully review each tool’s documentation to learn more about individual tool setup, limitations, and warnings.

If you’re using GitHub Copilot for Azure to scaffold a hosted agent that consumes the toolbox, the following skill references describe the same endpoint contract (env var, headers, MCP protocol, citation patterns, and troubleshooting) that the agent must implement:

• Toolbox reference — endpoint format, MCP protocol, OAuth consent handling, citation patterns, and troubleshooting.
• Use toolbox in a hosted agent — endpoint resolution, env-var contract, payload shape, code integration patterns, and tracing.

Step 1: Create a toolbox version

Create a toolbox version based on the tools you need.

When you include the Fabric IQ tool against a Power BI semantic model, restrict the tool surface with allowed_tools so the agent reasons over the schema and runs queries directly instead of pre-generating DAX. The recommended list is GetInstructions, DiscoverArtifacts, GetReportMetadata, GetSemanticModelSchema, ExecuteQuery, and ValueSearch — omit GenerateQuery. For end-to-end Fabric IQ setup, including OAuth and the Power BI semantic model endpoint, see Use the Fabric IQ tool.

Step 2: Get the toolbox MCP endpoint

Two endpoint patterns exist depending on your role:

Role	Endpoint	When to use
Toolbox developer	{project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1	Test or validate a specific version before promoting it to default.
Toolbox consumer	{project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1	Connect agents to the toolbox. Always serves the default_version. The first version you create is automatically set as the default.

The first version of a new toolbox is automatically promoted to default_version (v1). If you need to change the default later, see Promote a version to default.

In the Microsoft Foundry Toolkit for Visual Studio Code extension, copy the toolbox consumer endpoint from the Toolboxes view.

1. Select Foundry Toolkit in the Activity Bar.
2. Under My Resources, expand Your project name > Tools.
3. On the Toolboxes tab, locate your toolbox.
4. In the Endpoint URL column, copy the endpoint.

The Endpoint URL value is the toolbox consumer endpoint. To construct a version-specific endpoint, use the developer pattern shown in the previous table.

Step 3: Verify tool availability

Before running the full agent, confirm that the toolbox loads the expected tools by using an MCP client SDK against the endpoint. Use the version-specific endpoint to validate a version before promoting it to default.

Check — initialize: HTTP 200. If you skip the initialize step, subsequent calls fail.

Check — tools/list:

• len(tools) > 0 — empty means the toolbox version wasn’t provisioned correctly.
• Each tool has name, description, and inputSchema. For tool naming conventions, see the MCP specification.
• inputSchema has a properties field (some MCP servers omit this field, which breaks OpenAI).
• For MCP tools, names are prefixed with the server_label - for example, myserver.some_tool. For all other tool types, the name is the name field value or the default tool name.
• MCP tools include a _meta.tool_configuration block containing runtime settings such as require_approval. See Handle tool approval requirements.
• Note the exact parameter names for the call step (for example query vs queries).

Check - tools/call:

• No top-level error field. If present, inspect error.code. For standard MCP error codes, see the MCP specification:
  • -32006 → OAuth consent required (extract URL from error.message).
  • Other codes → server-side failure.
• result.content[] contains entries with "type": "text" - this is the tool output.
• For AI Search, check result.structuredContent.documents[] for chunk metadata (title, url, id, score).
• For File Search, check result.content[].resource._meta for chunk metadata (title, file_id, document_chunk_id, score).
• For Web Search, check result.content[].resource._meta.annotations[] for URL citations (type, url, title, start_index, end_index).
• For Fabric IQ, check result.structuredContent.documents[] for citation chunks. Each document includes title and url fields pointing back to the Fabric item (Ontology, data agent, or Power BI semantic model) used to ground the response.
• Watch for "ServerError" in text content - the tool executed but hit an internal error.

Tool-specific tools/call argument examples:

Tool type	Arguments
AI Search	{"query": "search text"}
File Search	{"queries": ["search text"]}
Code Interpreter	{"code": "print(2 ** 100)"}
Web Search	{"search_query": "weather in seattle"}
A2A	{"message": {"parts": [{"type": "text", "text": "Hello"}]}}
Fabric IQ	Varies by exposed tool — typically {"query": "..."} for query tools
Work IQ	{"message": {"parts": [{"type": "text", "text": "Hello"}]}}
MCP	{"query": "what is agent service"}

Step 4: Integrate the toolbox into your agent

Handle tool approval requirements

The toolbox returns a _meta.tool_configuration object into every tool entry returned by tools/list. When a tool has require_approval set to "always", the agent runtime must present the pending action to the user and wait for confirmation before invoking the tool. The MCP endpoint does not block tools/call — enforcement is entirely the agent runtime’s responsibility.

Read require_approval from tools/list

Each tool entry in a tools/list response includes a _meta block returned by the toolbox:

{
  "name": "myserver.my_tool",
  "description": "...",
  "inputSchema": { "type": "object" },
  "_meta": {
    "tool_configuration": {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "require_approval": "always"
    }
  }
}

require_approval value	Behavior
"always"	The agent must ask the user for confirmation before every invocation.
"never"	The agent can invoke the tool freely.

Implement approval gating (LangGraph)

Query tools/list at startup to build an approval map, then inject a constraint into the system prompt for any tool that requires approval:

async def _fetch_require_approval_tools(
    endpoint: str,
    auth: httpx.Auth,
    extra_headers: dict,
) -> dict[str, str]:
    async with httpx.AsyncClient(auth=auth, headers=extra_headers, timeout=30.0) as hc:
        payload = {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
        resp = await hc.post(endpoint, json=payload)
        resp.raise_for_status()
    return {
        t["name"]: t["_meta"]["tool_configuration"]["require_approval"]
        for t in resp.json().get("result", {}).get("tools", [])
        if t.get("_meta", {}).get("tool_configuration", {}).get("require_approval")
    }

After loading tools from the MCP client, detect which tools require approval and adjust the system prompt:

approval_map = await _fetch_require_approval_tools(
    TOOLBOX_ENDPOINT, toolbox_auth, extra_headers
)
always_approval = [name for name, val in approval_map.items() if val == "always"]

• Detection happens at startup. The approval check runs once when the agent initializes. There’s no per-call overhead.
• Graceful fallback. If no tools have require_approval: "always", the system prompt is unchanged and the agent behaves as before.
• require_approval is agent-enforced. The toolbox MCP proxy executes tools/call regardless of this setting. Your agent runtime is responsible for gating the call.

Configure require_approval on a tool

Set require_approval when you create a toolbox version. The MCP tool examples in Step 1 show both "always" and "never" values. You can also set it through the SDK:

Step 5: Manage toolbox versions

You can delete toolbox versions through the Python SDK, .NET SDK, JavaScript SDK, and REST API only. The azd CLI supports list, get, and publish (default-version promotion) operations.

Toolbox versions are immutable snapshots of a toolbox’s tool configuration. Every call to the create endpoint produces a new ToolboxVersionObject. The parent ToolboxObject has a default_version field that controls which version the MCP endpoint serves. Creating a new version doesn’t automatically promote it - you decide when to update default_version. This process lets you stage changes, test a new version independently, and promote it to production on your own schedule.

For the Azure Developer CLI, every mutating operation that targets the current default version — azd ai toolbox connection add/remove and azd ai toolbox skill add/remove — creates a new toolbox version that carries forward all previously attached connections and skills with the requested change applied. None of these commands automatically change default_version; run azd ai toolbox publish <toolbox-name> <version> when you’re ready to make the new version active. To inspect a pending (non-default) version, use azd ai toolbox show <name> --version <n>.

Object	Key fields	Description
ToolboxObject	id, name, default_version	The toolbox container. default_version points to the active version.
ToolboxVersionObject	id, name, version, description, created_at, tools[], policies	An immutable snapshot of the toolbox’s tool list at a point in time. policies.rai_config.rai_policy_name specifies the optional guardrail applied to this version.

Create a new version

Each create call produces a new version. If the toolbox doesn’t exist yet, the process automatically creates it. When you create the first version of a new toolbox, the default version is v1 until you manually update to another version.

The response is a ToolboxVersionObject containing the new version identifier.

List versions

Get a specific version

Promote a version to default

The MCP endpoint always serves the default_version. To switch which version is active, update the toolbox:

Delete a version

Configure tools

Choose the tool type and authentication pattern that match your scenario. Select the tab for your preferred SDK or deployment method.

Each tool’s azd tab below shows the declarative agent.yaml manifest consumed by azd ai agent init. To create a toolbox imperatively (without an agent project), use the generic four-step azd ai toolbox create --from-file workflow and apply the per-tool data shown in the following sections.

Multiple tool types

A single toolbox can bundle different tool types. The following example combines Web Search, Azure AI Search, and an MCP server in one toolbox:

{
  "description": "Web search, knowledge base search, and custom MCP server",
  "tools": [
    {
      "type": "web_search",
      "description": "Search the web for current information"
    },
    {
      "type": "azure_ai_search",
      "name": "my_aisearch",
      "description": "Search internal product documentation",
      "azure_ai_search": {
        "indexes": [
          {
            "index_name": "<INDEX_NAME>",
            "project_connection_id": "<CONNECTION_NAME>"
          }
        ]
      }
    },
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "require_approval": "never",
      "project_connection_id": "my-key-auth-connection"
    }
  ]
}

Each tool type (web_search, azure_ai_search, code_interpreter, file_search) can appear at most once without a name field. To include multiple instances of the same type, set a unique name on each instance - see the next example.

Multi-tool restrictions

You can include at most one instance of each built-in tool type without a name field in a toolbox. If you include two instances of the same type without a name, the API returns:

400 invalid_payload: Multiple tools without identifiers found...

Two instances of the same tool type

Use the name field to include multiple instances of the same tool type in one toolbox. Each named instance is treated as a separate tool and must have a unique name.

{
  "description": "Two Azure AI Search indexes in a single toolbox",
  "tools": [
    {
      "type": "azure_ai_search",
      "name": "product-search",
      "description": "Search product catalog and specifications",
      "azure_ai_search": {
        "indexes": [
          {
            "index_name": "<PRODUCT_INDEX_NAME>",
            "project_connection_id": "<PRODUCT_CONNECTION_NAME>"
          }
        ]
      }
    },
    {
      "type": "azure_ai_search",
      "name": "support-search",
      "description": "Search support tickets and troubleshooting guides",
      "azure_ai_search": {
        "indexes": [
          {
            "index_name": "<SUPPORT_INDEX_NAME>",
            "project_connection_id": "<SUPPORT_CONNECTION_NAME>"
          }
        ]
      }
    }
  ]
}

The following sections show each tool type’s configuration in detail.

Model Context Protocol (MCP)

The first time a user calls a toolbox with an OAuth-based MCP in a project, the MCP endpoint returns a CONSENT_REQUIRED error (code -32006) with a consent URL:

{
  "error": {
    "code": -32006,
    "message": "User consent is required. Please visit: https://..."
  }
}

This error is expected. Open the consent URL in a browser, complete the OAuth authorization flow, and then retry the agent call. Subsequent calls succeed without re-prompting.

Web Search

• Web Search uses Grounding with Bing Search and Grounding with Bing Custom Search, which are First Party Consumption Services governed by these Grounding with Bing terms of use and the Microsoft Privacy Statement.
• The Microsoft Data Protection Addendum doesn’t apply to data sent to Grounding with Bing Search and Grounding with Bing Custom Search. When you use Grounding with Bing Search and Grounding with Bing Custom Search, data transfers occur outside compliance and geographic boundaries.
• Use of Grounding with Bing Search and Grounding with Bing Custom Search incurs costs. See pricing for details.
• See the management section for information about how Azure admins can manage access to use of web search.

Use this pattern to add web search. No project connection is required for the web search with Grounding with Bing. To use a Grounding with custom Bing Search instance, add a web_search.custom_search_configuration object pointing to your Grounding with Bing Custom Search connection.

When Web Search returns results over MCP, the response is a resource content item containing the synthesized answer with inline Markdown source links. URL citations are in content[].resource._meta.annotations[]. For example:

{
  "jsonrpc": "2.0",
  "id": "ws-call-1",
  "result": {
    "_meta": {
      "tool_configuration": {
        "type": "web_search",
        "name": "web-search-default"
      }
    },
    "content": [
      {
        "type": "resource",
        "resource": {
          "uri": "about:web-search-answer",
          "mimeType": "text/plain",
          "text": "Here are the latest updates on Azure OpenAI Service...\n\n- **GPT-image-1 Release (January 7, 2026)** Microsoft introduced GPT-image-1 ([serverless-solutions.com](https://...)).\n\n..."
        },
        "annotations": {
          "audience": ["assistant"]
        },
        "_meta": {
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://www.serverless-solutions.com/blog/...",
              "title": "Microsoft Expands Azure AI Foundry with Powerful New OpenAI Models",
              "start_index": 741,
              "end_index": 879
            }
          ],
          "action": {
            "type": "search",
            "query": "Azure OpenAI service updates 2026",
            "queries": ["Azure OpenAI service updates 2026"]
          },
          "response_id": "resp_001fcebcc300..."
        }
      }
    ],
    "isError": false
  }
}

Azure AI Search

Configure tool parameters

Azure AI Search tool parameter	Required	Notes
project_connection_id	Yes	The resource ID of the project connection to Azure AI Search.
index_name	Yes	The name of the index in your Azure AI Search resource.
top_k	No	Defaults to 5.
query_type	No	Defaults to vector_semantic_hybrid. Supported values: simple, vector, semantic, vector_simple_hybrid, vector_semantic_hybrid.
filter	No	Applies to all queries the agent makes to the index.

The search results include chunk metadata in result.structuredContent.documents[]. Each document includes title, url, id, and score fields that you can use to generate citation details in your application.

Code Interpreter

Use this pattern to let the agent write and execute Python code. The pattern doesn’t require a project connection or extra configuration.

To upload a file for Code Interpreter to use through a toolbox, upload the file at the resource-level Files endpoint (POST {account_endpoint}/openai/v1/files) with the x-aml-project-id header. Unlike the prompt agent flow, files uploaded through the project-scoped Files endpoint (/api/projects/{name}/openai/v1/files) receive an owner_id that the toolbox container can’t verify, so tools/call fails with an ownership-verification error.

1. Get the project GUID from Azure Resource Manager. Use properties.amlWorkspace.internalId (dashed UUID format), not properties.internalId (no dashes — the toolbox container rejects it):

   ARM_TOKEN=$(az account get-access-token --query accessToken -o tsv)
   PROJECT_GUID=$(curl -s -H "Authorization: Bearer $ARM_TOKEN" \
     "https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}?api-version=2025-06-01" \
     | jq -r '.properties.amlWorkspace.internalId')
   

2. Upload the file at the account (resource) level with the x-aml-project-id header:

   TOKEN=$(az account get-access-token --resource https://ai.azure.com/.default --query accessToken -o tsv)
   curl -X POST "https://{account}.services.ai.azure.com/openai/v1/files" \
     -H "Authorization: Bearer $TOKEN" \
     -H "x-aml-project-id: $PROJECT_GUID" \
     -F "purpose=assistants" \
     -F "file=@your-file.csv"
   

The returned file id is the value you supply as <FILE_ID> in the tool configuration. Files are mounted in the sandbox at /mnt/data/{file-id}-{original-filename}. See Code Interpreter for additional upload examples and language-specific samples.

When Code Interpreter is used through a toolbox in a hosted agent, user isolation isn’t supported. All users in the same project share the same container context.

Download output files from Code Interpreter

When Code Interpreter produces output files (for example, a generated CSV or chart), use the following steps to list and download them.

Step 1: List files using the Container API

Extract the container_id from content[]._meta.container_id in the tools/call response, then call the Container Files API to list all files in the container:

GET {project_endpoint}/containers/{container_id}/files?api-version=v1
Authorization: Bearer {token}

The response returns a list of files with their names and IDs.

Step 2: Download the file using the File API

Use the file name returned from Step 1 to download the file via the File API download endpoint.

File Search

Use this pattern to let the agent search over uploaded files stored in a vector store. Provide vector_store_ids referencing vector stores already created in your Foundry project.

To create a file and vector store for use with a toolbox, upload the file at the resource-level Files endpoint with the x-aml-project-id header (the same requirement as Code Interpreter — see the previous section for how to obtain the project GUID from properties.amlWorkspace.internalId):

1. Upload your file: POST {account_endpoint}/openai/v1/files with purpose=assistants and header x-aml-project-id: {project-guid}.
2. Create a vector store: POST {account_endpoint}/openai/v1/vector_stores with the returned file ID and the same x-aml-project-id header.

The resulting vector store ID is the value you supply as <VECTOR_STORE_ID>. See File Search for full examples in each language.

When File Search is used through a toolbox in a hosted agent, user isolation isn’t supported. All users in the same project share access to the same vector store.

When File Search returns results over MCP, chunk metadata is embedded in the tool response content as 【index†filename†file_id【 markers. For example:

{
  "jsonrpc": "2.0",
  "id": "fs-call-1",
  "result": {
    "content": [
      {
        "type": "resource",
        "resource": {
          "uri": "file://assistant-tvfqncbtruyffxkfewenyy/",
          "_meta": {
            "title": "mcp-test-file.txt",
            "file_id": "assistant-TVfQnCBtRuyfFxkfeweNYY",
            "document_chunk_id": "f7327b7f-5ed0-43c6-9bee-e8e9552afcb5",
            "score": 0.03333333507180214
          },
          "text": "# 【0†mcp-test-file.txt†assistant-TVfQnCBtRuyfFxkfeweNYY【\nContent Snippet:\nAzure OpenAI Service is a cloud service..."
        }
      }
    ]
  }
}

The _meta block inside each resource item contains the title, file_id, document_chunk_id, and relevance score for the matched chunk. Use these metadata fields in your application to generate citation details or deep-link back to the source file.

OpenAPI

Use this pattern to expose any REST API described by an OpenAPI spec. Choose the auth.type that matches your API’s security model.

When managed identity auth is used, you must assign the appropriate RBAC role to your Foundry project’s managed identity on the target service. For example, assign Reader or higher on the target Azure resource. Without this assignment, the agent receives a 401 Unauthorized response when calling the API. For full setup steps, see Authenticate by using managed identity.

Agent-to-Agent (A2A)

Use this pattern to call another agent as a tool. Provide the base URL of the remote agent and, if it requires authentication, a project connection.

Fabric IQ

Use this pattern to give the agent access to Microsoft Fabric data - ontologies, data agents, and Power BI semantic models - through Fabric IQ. Provide the project connection, MCP server URL, and server label for the target Fabric item.

For server_url patterns by Fabric item type, see Find your Fabric IQ server details.

Annotation chunks are returned in result.structuredContent.documents[]. Each document includes title and url fields that you can use to generate citation details in your application.

Tool Search

Use this pattern to enable intent-based tool routing. When toolbox_search_preview is included in a toolbox, the platform selects the most relevant tools for each request instead of exposing all tools to the model at once. No additional configuration is required.

toolbox_search_preview is a configuration directive that activates tool search. It doesn’t appear in tools/list responses and doesn’t count toward the unnamed-tool-per-type limit.

When tool search is enabled, Foundry injects two meta-tools alongside your toolbox tools: tool_search and call_tool. The call_tool meta-tool acts as a proxy that lets agent frameworks invoke any discovered tool by name through a single declared entry point. This avoids schema-validation errors that occur when a framework tries to call a tool that wasn’t present in the initial tools/list. If your framework supports direct tool calls without schema pre-validation, you can also call a discovered tool directly after finding it with tool_search.

In Foundry Toolkit for Visual Studio Code, select Tool search on the Build a Custom Toolbox tab when you create or edit a toolbox. For more information, see Enable tool search in a toolbox.

Work IQ

Use this pattern to give the agent access to the user’s Microsoft 365 work context - email, meetings, files, and chats - through Work IQ. Provide a project connection to your Work IQ endpoint.

Browser Automation

Troubleshoot

Symptom	Likely cause	Fix
tools/list returns zero tools for MCP or A2A tools	Invalid or missing connection credentials for the remote MCP server or A2A agent. The toolbox can’t retrieve tool manifests from the remote endpoint without valid auth.	Verify the project_connection_id exists in your Foundry project and the credentials are correct. Try connecting to the MCP server directly to test the auth setup. If using managed identity (PMI, agent identity, or MI), verify the correct RBAC role assignments for the caller on the target resource.
tools/list returns zero tools for OpenAPI tools	Invalid OpenAPI spec. The toolbox constructs the tool manifest from the spec, which fails if the spec is malformed.	Validate your OpenAPI spec content. Check that it conforms to OpenAPI 3.0 or 3.1 and includes valid paths, operationId values, and parameter schemas. If using managed identity auth, also verify RBAC role assignments on the target service.
tools/list returns fewer tools than expected	The allowed_tools filter contains incorrect or misspelled tool names. Tool names are case-sensitive and must follow the MCP specification for tool names (no whitespace or special characters).	Remove allowed_tools temporarily and call tools/list to get the full tool list. Use the exact names from the response to set values for allowed_tools.
tools/list returns zero tools (other tool types)	Toolbox not fully provisioned or tool type unsupported in region. For built-in tools (Web Search, AI Search, Code Interpreter, File Search), tool manifests are constructed server-side and don’t require auth — if they return empty, the toolbox version might not be provisioned yet.	Wait 10 seconds and retry.
400 Multiple tools without identifiers	Two unnamed tool types in one toolbox	Keep at most one unnamed type; add server_label to all MCP tools.
CONSENT_REQUIRED (code -32006)	OAuth connection requires user consent	Open the consent URL in a browser and complete the OAuth flow, then retry.
401 on MCP calls	Expired token or wrong scope	Use scope https://ai.azure.com/.default and refresh the token.
Tool names not matching	MCP tool names are prefixed with server_label	Use {server_label}.{tool_name} format (for example, myserver.get_info).
500 on send_ping()	Toolbox MCP server doesn’t implement the MCP ping method.	Don’t call send_ping(). If your framework calls it automatically (for example, Microsoft Agent Framework’s MCPStreamableHTTPTool._ensure_connected()), disable the ping check or override the method with a no-op.
500 on prompts/list	The Foundry MCP server doesn’t implement prompts/list.	Pass load_prompts=False (or equivalent) to your MCP client constructor.
500 with non-streaming tools/call	Non-streaming mode (stream=False) isn’t supported for toolbox MCP endpoints.	Always use stream=True when calling toolbox MCP tools.
500 on tools/list	Transient server error	Retry after a few seconds.
Environment variables overwritten at runtime	The platform reserves all environment variables prefixed with FOUNDRY_ and might silently overwrite user-defined values.	Rename custom environment variables to avoid the FOUNDRY_ prefix (for example, use TOOLBOX_MCP_ENDPOINT instead of FOUNDRY_TOOLBOX_ENDPOINT).

Configure guardrails

Apply a named guardrail policy to a toolbox version to enforce responsible AI content filtering on tool inputs and outputs. The guardrail runs at the toolbox layer, independently of any model-level content filter.

A guardrail is referenced by its policy name, which you configure in the Foundry portal under Guardrails. Set policies.rai_config.rai_policy_name to the name of the policy when creating a toolbox version.

Attach skills to a toolbox

Attach skills to a toolbox version to make them available to agents through the toolbox MCP endpoint. Each skill reference specifies the skill name and an optional version. Omit version to use the skill’s default_version; pin a version string to use an immutable snapshot.

Skills attached to a toolbox must exist in the same Foundry project. Cross-project references aren’t supported.

When an agent or MCP client connects to the toolbox endpoint, skills are exposed as MCP Resources. The MCP client or agent framework must support the MCP Resources protocol to auto-discover and load skills. To verify that skills are discoverable, call resources/list on the toolbox MCP endpoint and confirm your skill names appear in the response.

Virtual network support

When your Foundry project uses network isolation (private link), not all toolbox tool types are supported. The following table shows the support status for each tool type and how traffic flows in a network-isolated environment.

Tool type	VNet support	Traffic flow
MCP	✅ Supported	Through your VNet subnet
Azure AI Search	✅ Supported	Through private endpoint
Code Interpreter	✅ Supported	Microsoft backbone network
Web Search	✅ Supported	Public endpoint
OpenAPI	✅ Supported	Depends on target API network configuration
File Search	❌ Not supported	Not yet available
Agent-to-Agent (A2A)	✅ Supported	Through private endpoint
Fabric IQ	❌ Not supported	Not yet available
Work IQ	❌ Not supported	Not yet available
Browser Automation	❌ Not supported	Not yet available

For full network isolation setup instructions, including VNet injection for the agent client, DNS configuration, and private endpoint requirements, see Configure network isolation for Microsoft Foundry.

Region and model compatibility

Toolbox availability depends on two factors beyond the project region:

• Region: Some tool types aren’t available in every region that supports the agent service. For example, a region that supports the toolbox endpoint might not support all built-in tool types.

Before deploying a toolbox, verify that your target region supports the tool types you plan to use. For the full compatibility tables, see Tool support by region and model.

Related content

• Connect agents to Model Context Protocol servers
• Add MCP server authentication
• Web search tool
• Azure AI Search tool
• Guardrails overview
• Manage skills
• Deploy a Hosted agent
• Add a connection to your project
• Configure network isolation for Microsoft Foundry