Foundry Toolbox — Tool Integration for Hosted Agents

Hosted agents access Foundry-managed tools through a Toolbox MCP endpoint. Unlike prompt agents that wire tools directly, hosted agents connect to a single MCP-compatible endpoint that exposes all configured tools. The platform handles credential injection, token refresh, and policy enforcement.

Quick Reference

Workflow

User wants tools in hosted agent
    │
    ▼
Step 1: Does user have a toolbox?
    │  ├─ Yes → Step 2
    │  └─ No → Ask, then Step 1b to create one
    │
    ▼
Step 2: Generate agent code with toolbox integration

After code generation, return to the parent skill's Step 6 (Verify Startup) to run the agent and send a test request. Toolbox auth/connection errors are expected without real Azure credentials — the key validation is that the HTTP server starts and the agent accepts requests.

Step 1: Resolve Toolbox

If the user provides a toolbox name or endpoint URL, or the project already references a toolbox (e.g., in .env or agent.manifest.yaml) → proceed to Step 2.

Otherwise, ask: "Do you have an existing Foundry Toolbox, or should I help create one?" Then proceed to Step 1b.

Step 1b: Create a Toolbox (if needed)

Available tool types: Web Search, Azure AI Search, Code Interpreter, File Search, MCP Server, OpenAPI, Agent-to-Agent (A2A). For details, see Configure tools.

Step 2: Generate Agent Code with Toolbox

The sample repo provides integration patterns for both Python and C#. Read the sample code and adapt it to the user's project.

Python samples:

C# (.NET) samples:

Notes: (apply to all patterns, both Python and C#):

• Auth: Inject a bearer token with scope https://ai.azure.com/.default on every request (Python: httpx.Auth subclass; C#: DefaultAzureCredential + BearerTokenAuthenticationPolicy).
• Header: Always include Foundry-Features: Toolboxes=V1Preview.
• MCP client: Pass load_prompts=False — the toolbox endpoint does not support prompts/list.
• Endpoint: Construct from {project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1.

💡 Tip: If MCP tools have require_approval: "always" in _meta.tool_configuration, the agent runtime must ask the user for confirmation before invoking. The toolbox endpoint does not enforce this — your agent code is responsible.

Toolbox Reference

Endpoint Format

The toolbox MCP endpoint is constructed from the project endpoint + toolbox name:

• Project endpoint format: https://<account>.services.ai.azure.com/api/projects/<project>
• The latest-version endpoint always serves the toolbox’s default_version.
• Use the specific-version endpoint to test a version before promoting it.
• Required header on every request: Foundry-Features: Toolboxes=V1Preview
• ?api-version=v1 query parameter is required — requests without it return HTTP 400.

MCP Protocol

Toolboxes use Model Context Protocol (MCP) — JSON-RPC 2.0 over HTTP POST:

• initialize — Handshake to establish an MCP session. Returns a mcp-session-id header to include in subsequent requests.
• tools/list — Returns all available tools with names, descriptions, and input schemas.
• tools/call — Invokes a tool with arguments and returns structured results.

prompts/list is not supported by the toolbox endpoint. Always pass load_prompts=False to MCP client constructors.

Authentication

• Agent → Toolbox: Azure AD bearer token with scope https://ai.azure.com/.default, refreshed on every request.
• Toolbox → External Services: Managed by the platform via project connections (API keys, OAuth, managed identity).

OAuth Consent Handling

When a toolbox includes an OAuth-based MCP connection (e.g., GitHub OAuth), the first call triggers a CONSENT_REQUIRED error (MCP error code -32006). The error message contains the consent URL.

Agent code must handle this:

1. Catch MCP error code -32006 from tools/call or during MCP session initialization.
2. Extract the consent URL from the error message.
3. Log the URL and surface it to the user (e.g., print to stdout or return in the agent response).
4. After the user completes the OAuth flow in a browser, retry the call — subsequent calls succeed without re-prompting.

This is a one-time flow per user per OAuth connection in a project. The agent should not silently swallow this error.

Testing the Toolbox Endpoint

Before running the full agent, verify the toolbox MCP endpoint works end-to-end. Use az login for authentication, then test the three MCP operations in order:

1. Get a bearer token:

TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
TOOLBOX_URL="https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<name>/mcp?api-version=v1"

2. Initialize MCP session:

curl -sS -X POST "$TOOLBOX_URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: Toolboxes=V1Preview" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"debug","version":"1.0.0"}}}' \
  -D - | head -20

Save the mcp-session-id header from the response for subsequent calls.

3. List tools:

curl -sS -X POST "$TOOLBOX_URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: Toolboxes=V1Preview" \
  -H "mcp-session-id: <session-id-from-step-2>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | jq .

Checklist:

• Response contains result.tools[] with len > 0
• Each tool has name, description, and inputSchema with a properties field
• MCP tool names for remote servers are prefixed with server_label (e.g., myserver.get_info)

4. Call a tool (optional):

curl -sS -X POST "$TOOLBOX_URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: Toolboxes=V1Preview" \
  -H "mcp-session-id: <session-id-from-step-2>" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"<tool_name>","arguments":{"query":"test"}}}' | jq .

For a Python-based debug client, see the _McpToolboxClient class in the BYO toolbox sample main.py — it implements initialize, list_tools, and call_tool using raw httpx calls.

Troubleshooting