Use a toolbox with a hosted agent in Microsoft Foundry

Connect a hosted agent to a Microsoft Foundry toolbox over MCP by using Agent Framework, LangGraph, the Foundry Toolkit, or the Azure Developer CLI.

A hosted agent runs your code in Foundry Agent Service. In this article, you connect that code to a toolbox so the agent discovers and calls the toolbox tools through one Model Context Protocol (MCP) endpoint.

If you use a coding agent like GitHub Copilot, the Microsoft Foundry Skill can help connect the hosted agent to a toolbox endpoint and adapt the sample to your own tools.

Prerequisites

• A toolbox with at least one tool and a default version.
• A Microsoft Foundry project with a deployed model.
• A hosted-agent project. To create the agent and toolbox together, complete the toolbox quickstart.
• A development identity that can access the Foundry project. Sign in locally with az login or azd auth login before you run a sample.
• Any permissions required by the services behind the toolbox tools. For tools that use OAuth or Microsoft Entra identity passthrough, review Toolbox authentication before you deploy the agent.

Choose the toolbox endpoint

Use the toolbox consumer endpoint for an agent that should follow the toolbox’s default_version:

https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/mcp?api-version=v1

When you promote another toolbox version to default, an agent that uses this endpoint gets the new version without an endpoint change or redeployment.

Use a version-specific developer endpoint only when you need to test an immutable version before promotion:

https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1

Authenticate the agent to the toolbox

The agent authenticates to the toolbox endpoint with its Microsoft Entra identity and the https://ai.azure.com/.default scope. The connection for each toolbox tool determines which identity or credential reaches the downstream service.

Don’t put downstream API keys or OAuth tokens in the agent code. Configure those credentials on the project connection that the toolbox tool references. For details about supported authentication types, consent, and role requirements, see Toolbox authentication.

Connect the hosted agent

Enforce tool approval

Each entry returned by MCP tools/list can contain a _meta.tool_configuration.require_approval value:

Value	Required runtime behavior
always	Show the proposed tool name and arguments to the user, wait for an explicit approval, and invoke the tool only after approval. Repeat this process for every call.
never	Invoke the tool without an approval prompt.

The toolbox MCP endpoint doesn’t block tools/call when require_approval is always. Your agent runtime must enforce the setting before every invocation. A system-prompt instruction alone doesn’t enforce approval.

Use require_approval: never unless your runtime can pause the pending tool call, collect the user’s decision, and resume or reject that exact call. To configure the value on a toolbox tool, see Configure tool approval.

Troubleshoot the connection

Symptom	Cause and resolution
The agent returns no toolbox tools.	Confirm that the toolbox has a default version, the toolbox name matches, and the agent identity can access the Foundry project.
Startup or readiness fails.	A toolbox enumerates all its tool sources together. Check agent logs for a failing connection, unavailable MCP server, or invalid allowed-tool name. Fix or remove that source, create a new version, and promote it.
A tool returns 401 or 403.	Verify the agent-to-toolbox identity and the downstream authentication configured on the tool’s project connection. These are separate authorization boundaries.
A tool requests consent.	Return the consent request to the signed-in user and resume the call after consent. Review the tenant and role requirements in Toolbox authentication.
A version change doesn’t appear.	Confirm that the agent uses the unversioned consumer endpoint and that you promoted the intended version to default_version.

Related content

• Create and manage a toolbox
• Toolbox authentication
• Quickstart: Build a toolbox and use it with a hosted agent