subagentic.ai RSS X YouTube GitHub
AI-generated illustration

How-Tos

Point a Foundry hosted agent at a toolbox MCP endpoint

Connect a Foundry hosted agent to a toolbox MCP endpoint, keep secrets on the project connection, and enforce tool approval in the runtime.

microsoft-foundrymcphosted-agents

A hosted agent runs your code in Microsoft Foundry Agent Service. Microsoft Learn's guide to using a toolbox with a hosted agent shows how that code discovers and calls toolbox tools through one Model Context Protocol (MCP) endpoint. Point it at the unversioned consumer URL so it follows default_version, authenticate with the agent's Microsoft Entra identity, and leave downstream secrets on the project connection. Approval is a runtime step, not a system prompt: the toolbox endpoint does not block a call just because the tool asked for approval.

Prerequisites

Microsoft's guide starts from a toolbox with at least one tool and a default version, a Microsoft Foundry project with a deployed model, and a hosted-agent project. To create the agent and toolbox together, complete the toolbox quickstart the guide names. Sign in locally with az login or azd auth login before you run a sample, using a development identity that can access the Foundry project. Services behind the tools still need their own permissions. For OAuth or Microsoft Entra identity passthrough, review Toolbox authentication before you deploy.

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

Choose the toolbox endpoint

Use the consumer endpoint when the agent 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 on this endpoint gets the new version without an endpoint change or a 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

For user delegation with MCP and other tools, connect those tools through a Foundry toolbox. When you add that toolbox to a Microsoft Agent Framework hosted agent, use FoundryToolbox in Python or AddFoundryToolboxes in .NET.

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 decides which identity or credential reaches the downstream service. Do not put downstream API keys or OAuth tokens in the agent code. Configure those credentials on the project connection the toolbox tool references. Authentication types, consent, and role requirements are in Toolbox authentication, which the hosted-agent guide points to instead of repeating.

Connect with Microsoft Agent Framework

The maintained Python sample uses FoundryToolbox from the Agent Framework hosting package. The class resolves the toolbox from TOOLBOX_ENDPOINT, or from FOUNDRY_PROJECT_ENDPOINT and TOOLBOX_NAME. It also authenticates MCP requests and forwards the hosted runtime's per-request call ID.

Follow the toolbox quickstart for the full initialization and deployment walkthrough. The hosted-agent toolbox sample declares its connections and toolbox in azure.yaml. Deploy those dependencies before starting the local agent. azd ai agent run does not create them.

The sample maps the deployed toolbox's versioned endpoint to TOOLBOX_ENDPOINT. Setting only TOOLBOX_NAME does not override a configured TOOLBOX_ENDPOINT. To use an existing toolbox instead, update the endpoint binding in the agent service's env configuration. If the application accepts only a complete URL, set TOOLBOX_ENDPOINT to the unversioned consumer endpoint.

After the quickstart setup, run these commands from the initialized project root.

azd ai agent run

In another terminal, verify that the agent discovers the toolbox tools:

azd ai agent invoke --local "List the tools you can use and briefly describe each one."

The response lists the tools the toolbox returns from MCP tools/list. If it contains no toolbox tools, use the checks in Microsoft's troubleshooting section for this connection.

Connect with LangGraph

Use AzureAIProjectToolbox when the hosted-agent code is built with LangGraph. The integration loads the toolbox tools as LangChain tools and handles authentication to the consumer endpoint.

pip install "langchain-azure-ai[hosting]>=1.2.8"

Set FOUNDRY_PROJECT_ENDPOINT in the hosted-agent environment. The runtime supplies this value after deployment. Set it yourself for local development. Load the tools by toolbox name:

import asyncio

from langchain_azure_ai.tools import AzureAIProjectToolbox

async def load_tools():
   toolbox = AzureAIProjectToolbox(toolbox_name="<toolbox-name>")
   tools = await toolbox.get_tools()
   print("\n".join(tool.name for tool in tools))

asyncio.run(load_tools())

The output contains the names MCP tools/list returns. Pass the loaded tools to your LangGraph agent and run a prompt that requires one of them. Microsoft points to the LangGraph toolbox sample for a complete implementation.

Register the toolbox in .NET

AddFoundryToolboxes constructs the consumer endpoint from FOUNDRY_PROJECT_ENDPOINT, calls MCP tools/list during startup, and adds the discovered tools to each agent request. Install the .NET 10 SDK and Azure CLI before you run the maintained sample. Start from the public hosted toolbox sample, or add the Foundry hosting package to an existing Agent Framework host.

Set these variables for local development:

AZURE_AI_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
AZURE_AI_MODEL_DEPLOYMENT_NAME=<model-deployment-name>
TOOLBOX_NAME=<toolbox-name>

Foundry supplies FOUNDRY_PROJECT_ENDPOINT to the deployed container. Keep the toolbox name in TOOLBOX_NAME. Other FOUNDRY_* variable names are reserved by the hosted runtime.

In Program.cs, register the agent with AddFoundryResponses, then register the toolbox with AddFoundryToolboxes(credential, toolboxName). After you build the web application, call MapFoundryResponses before Run. The public sample includes the required imports, packages, agent construction, and credential setup. Start the host and invoke it with a prompt that requires a toolbox tool. The /readiness endpoint returns an unhealthy status when the host cannot enumerate the toolbox tools.

The hosted-agent toolbox integrations in Microsoft's article are available for Python and .NET. From another runtime, use an MCP Streamable HTTP client, authenticate with a token for https://ai.azure.com/.default, and implement the hosted-agent runtime contract.

Scaffold in VS Code, or pass the name with azd

The Microsoft Foundry Toolkit for Visual Studio Code can scaffold a hosted-agent sample connected to a toolbox. Install Visual Studio Code, the Microsoft Foundry Toolkit extension, and the extension pack for your language. In the Activity Bar, select Foundry Toolkit. Under My Resources, expand your project, then Tools. On the Toolboxes tab, select Scaffold code template, choose a project folder in the Command Palette, and finish the local run and deployment steps in the generated README.md. Run a prompt that requires a toolbox tool and confirm the agent calls the expected tool.

For a sample that already constructs the consumer endpoint from FOUNDRY_PROJECT_ENDPOINT, install Azure Developer CLI (azd) 1.25 or later and the microsoft.foundry extension.

Inspect the toolbox and its current default version:

azd ai toolbox show <toolbox-name> --output json

The output uses the endpoint property. That endpoint identifies the selected version and is useful for testing that version. Store the toolbox name, then run locally or deploy:

azd env set TOOLBOX_NAME <toolbox-name>
azd ai agent run
azd deploy

If the application accepts only a complete URL, set TOOLBOX_ENDPOINT to the unversioned consumer endpoint.

Enforce tool approval in the runtime

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

  • always: show the proposed tool name and arguments, wait for an explicit approval, and invoke the tool only after approval. Repeat this for every call.
  • never: invoke the tool without an approval prompt.

The toolbox MCP endpoint does not block tools/call when require_approval is always. Your agent runtime must enforce the setting before every invocation. A system-prompt instruction alone does not enforce approval. Use require_approval: never unless the runtime can pause the pending tool call, collect the user's decision, and resume or reject that exact call. To set the value on a toolbox tool, follow Configure tool approval in Microsoft's toolbox article.

If the connection fails

If startup fails during initialization or tools/list, diagnose the discovery failure separately from tool execution. Toolbox troubleshooting covers discovery denials, HTTP 431, timeouts, missing A2A identity context, and shell-availability errors. If skill discovery succeeds but reading SKILL.md fails, verify skill-resource access with the deployed identity. A successful local test does not verify the deployed client's permissions.

If the agent returns no toolbox tools, confirm a default version, a matching toolbox name, and that the agent identity can access the Foundry project. If startup or readiness fails, the toolbox enumerates all of its tool sources together. Check agent logs for a failing connection, an unavailable MCP server, or an invalid allowed-tool name. Fix or remove that source, create a new version, and promote it. A 401 or 403 means two authorization boundaries: the agent-to-toolbox identity, and the downstream authentication on the tool's project connection. A call can succeed without those status codes and still use an unexpected user. Do not hard-code or reuse the call ID across user requests. Use FoundryToolbox in Python or AddFoundryToolboxes in .NET with the Foundry hosting integration to forward the current request's caller context, and test the deployed agent with two users who have different permissions. Return a consent request to the signed-in user and resume the call after consent. If a version change does not appear, confirm that the agent uses the unversioned consumer endpoint and that you promoted the intended version to default_version.

Complete the toolbox quickstart if the agent and toolbox are not in place yet. Then run the local invoke command and confirm the names from tools/list come back. Before you set require_approval to always, make the runtime pause that exact call, collect approval, and resume or reject it. Read Toolbox authentication before you deploy a tool that passes a user identity downstream.

Sources