1# Foundry Toolbox — Tool Integration for Hosted Agents
2 
3Hosted 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.
4 
5## Quick Reference
6 
7| Property | Value |
8|----------|-------|
9| **Toolbox Docs** | https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox |
10| **Default Sample (Python)** | https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/toolbox/maf |
11| **Python Hosted Agent — `responses`** | https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/bring-your-own/responses |
12| **Python Hosted Agent — `invocations`** | https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/bring-your-own/invocations |
13| **C# (.NET) Samples** | https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/toolbox |
14| **Supported Tool Types & Auth** | https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/toolbox/SUPPORTED_TOOLBOX_TOOLS.md |
15 
16## Workflow
17 
18```
19User wants tools in hosted agent
20    │
21    ▼
22Step 1: Does user have a toolbox?
23    │  ├─ Yes → Step 2
24    │  └─ No → Ask, then Step 1b to create one
25    │
26    ▼
27Step 2: Generate agent code with toolbox integration
28```
29 
30After 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.
31 
32### Step 1: Resolve Toolbox
33 
34If 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.
35 
36Otherwise, ask: _"Do you have an existing Foundry Toolbox, or should I help create one?"_ Then proceed to Step 1b.
37 
38### Step 1b: Create a Toolbox (if needed)
39 
40**Available tool types:** Web Search, Azure AI Search, Code Interpreter, File Search, MCP Server, OpenAPI, Agent-to-Agent (A2A). For details, see [Configure tools](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox#configure-tools).
41 
42| Method | When to use | References |
43|--------|-------------|------------|
44| **azd** — preferred | AI can generate `agent.manifest.yaml` and run `azd provision` | [Toolbox docs — azd tab](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox), [`toolbox/azd/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/toolbox/azd) (multiple scenario manifests covering tool types + auth patterns) |
45| **SDK (Python, .NET, JS)** | AI can generate code to create toolbox programmatically | [Toolbox docs](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox), Python: [`sample_toolboxes_crud.py`](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/toolbox/sample_toolboxes_crud.py), C#: [`csharp/toolbox/crud-sample/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/toolbox/crud-sample) |
46| **REST API** | AI can generate HTTP calls | [Toolbox docs — REST API tab](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox) |
47| **Foundry Toolkit (VS Code)** — manual | Direct user to create via VS Code extension | [Foundry Toolkit](https://aka.ms/foundrytk), [Tool Catalog](https://code.visualstudio.com/docs/intelligentapps/tool-catalog), [Toolbox docs — VS Code tab](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox) |
48| **Foundry Portal** — manual | Direct user to create via portal UI | [Toolbox docs](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox) |
49 
50### Step 2: Generate Agent Code with Toolbox
51 
52The sample repo provides integration patterns for both Python and C#. Read the sample code and adapt it to the user's project.
53 
54**Python samples:**
55 
56| Sample | Framework | Protocol | When to use |
57|--------|-----------|----------|-------------|
58| [`toolbox/maf/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/toolbox/maf) — recommended | Agent Framework (MAF) | Responses | **Default choice** |
59| [`bring-your-own/responses/langgraph-toolbox/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/bring-your-own/responses/langgraph-toolbox) | LangGraph (BYO) | Responses | LangGraph hosted agent with toolbox |
60| [`toolbox/copilot-sdk/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/toolbox/copilot-sdk) | GitHub Copilot SDK | Responses | Copilot SDK with toolbox tools |
61| [`bring-your-own/responses/bring-your-own-toolbox/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/bring-your-own/responses/bring-your-own-toolbox) | Generic MCP (BYO) | Responses | Raw `httpx` MCP client — works with any framework |
62| [`bring-your-own/invocations/toolbox/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/bring-your-own/invocations/toolbox) | Generic MCP (BYO) | Invocations | Toolbox via Invocations protocol |
63 
64**C# (.NET) samples:**
65 
66| Sample | Description |
67|--------|-------------|
68| [`csharp/toolbox/maf/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/toolbox/maf) — recommended | Agent Framework agent with toolbox MCP (Responses protocol) |
69 
70**Notes:** (apply to all patterns, both Python and C#):
71- Auth: Inject a bearer token with scope `https://ai.azure.com/.default` on every request (Python: `httpx.Auth` subclass; C#: `DefaultAzureCredential` + `BearerTokenAuthenticationPolicy`).
72- Header: Always include `Foundry-Features: Toolboxes=V1Preview`.
73- MCP client: Pass `load_prompts=False` — the toolbox endpoint does not support `prompts/list`.
74- Endpoint: Construct from `{project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1`.
75 
76> 💡 **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.
77 
78## Toolbox Reference
79 
80### Endpoint Format
81 
82The toolbox MCP endpoint is constructed from the **project endpoint** + **toolbox name**:
83 
84| Endpoint | URL |
85|----------|-----|
86| Latest version (default) | `{project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1` |
87| Specific version | `{project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1` |
88 
89- **Project endpoint** format: `https://<account>.services.ai.azure.com/api/projects/<project>`
90- The latest-version endpoint always serves the toolbox’s `default_version`.
91- Use the specific-version endpoint to test a version before promoting it.
92- **Required header** on every request: `Foundry-Features: Toolboxes=V1Preview`
93- `?api-version=v1` query parameter is **required** — requests without it return HTTP 400.
94 
95### MCP Protocol
96 
97Toolboxes use **Model Context Protocol (MCP)** — JSON-RPC 2.0 over HTTP POST:
98 
99- **`initialize`** — Handshake to establish an MCP session. Returns a `mcp-session-id` header to include in subsequent requests.
100- **`tools/list`** — Returns all available tools with names, descriptions, and input schemas.
101- **`tools/call`** — Invokes a tool with arguments and returns structured results.
102 
103> `prompts/list` is **not supported** by the toolbox endpoint. Always pass `load_prompts=False` to MCP client constructors.
104 
105### Authentication
106 
107- **Agent → Toolbox:** Azure AD bearer token with scope `https://ai.azure.com/.default`, refreshed on every request.
108- **Toolbox → External Services:** Managed by the platform via project connections (API keys, OAuth, managed identity).
109 
110### OAuth Consent Handling
111 
112When 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.
113 
114**Agent code must handle this:**
1151. Catch MCP error code `-32006` from `tools/call` or during MCP session initialization.
1162. Extract the consent URL from the error message.
1173. Log the URL and surface it to the user (e.g., print to stdout or return in the agent response).
1184. After the user completes the OAuth flow in a browser, retry the call — subsequent calls succeed without re-prompting.
119 
120> This is a one-time flow per user per OAuth connection in a project. The agent should not silently swallow this error.
121 
122### Testing the Toolbox Endpoint
123 
124Before 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:
125 
126**1. Get a bearer token:**
127```bash
128TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
129TOOLBOX_URL="https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<name>/mcp?api-version=v1"
130```
131 
132**2. Initialize MCP session:**
133```bash
134curl -sS -X POST "$TOOLBOX_URL" \
135  -H "Authorization: Bearer $TOKEN" \
136  -H "Content-Type: application/json" \
137  -H "Foundry-Features: Toolboxes=V1Preview" \
138  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"debug","version":"1.0.0"}}}' \
139  -D - | head -20
140```
141Save the `mcp-session-id` header from the response for subsequent calls.
142 
143**3. List tools:**
144```bash
145curl -sS -X POST "$TOOLBOX_URL" \
146  -H "Authorization: Bearer $TOKEN" \
147  -H "Content-Type: application/json" \
148  -H "Foundry-Features: Toolboxes=V1Preview" \
149  -H "mcp-session-id: <session-id-from-step-2>" \
150  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | jq .
151```
152 
153**Checklist:**
154- Response contains `result.tools[]` with `len > 0`
155- Each tool has `name`, `description`, and `inputSchema` with a `properties` field
156- MCP tool names for remote servers are prefixed with `server_label` (e.g., `myserver.get_info`)
157 
158**4. Call a tool (optional):**
159```bash
160curl -sS -X POST "$TOOLBOX_URL" \
161  -H "Authorization: Bearer $TOKEN" \
162  -H "Content-Type: application/json" \
163  -H "Foundry-Features: Toolboxes=V1Preview" \
164  -H "mcp-session-id: <session-id-from-step-2>" \
165  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"<tool_name>","arguments":{"query":"test"}}}' | jq .
166```
167 
168> For a Python-based debug client, see the `_McpToolboxClient` class in the [BYO toolbox sample `main.py`](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/bring-your-own-toolbox/main.py) — it implements `initialize`, `list_tools`, and `call_tool` using raw `httpx` calls.
169 
170## Troubleshooting
171 
172| Error | Cause | Resolution |
173|-------|-------|------------|
174| CONSENT_REQUIRED (code -32006) | OAuth MCP connection needs user consent | Open consent URL in browser, complete OAuth flow, retry |
175| 401 on MCP calls | Expired token or wrong scope | Use scope `https://ai.azure.com/.default` and refresh token |
176| 500 on `prompts/list` | Not supported by toolbox endpoint | Pass `load_prompts=False` to MCP client constructor |
177| 500 with non-streaming `tools/call` | Non-streaming not supported | Always use `stream=True` for toolbox MCP tools |
178