45 lines
3.2 KiB
Markdown
45 lines
3.2 KiB
Markdown
# Toolbox MCP protocol, tool naming & testing
|
|
|
|
## Endpoint URL details
|
|
- **Consumer** — `{project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1`. Always serves the `default_version`. Connect agents here so promoting a version needs no redeploy.
|
|
- **Developer** — `{project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1`. Test a specific version before promoting.
|
|
- `?api-version=v1` is **required** — requests without it return HTTP 400.
|
|
- Auth: bearer token with scope `https://ai.azure.com/.default`.
|
|
|
|
## MCP protocol
|
|
|
|
Toolboxes use **Model Context Protocol (MCP)** — JSON-RPC 2.0 over HTTP POST:
|
|
|
|
- **`initialize`** — optional handshake. `tools/list` / `tools/call` work without it. If you call it and the server returns an `mcp-session-id` header, resend it on subsequent calls.
|
|
- **`tools/list`** — returns all tools with names, descriptions, and input schemas.
|
|
- **`tools/call`** — invokes a tool and returns structured results. Plain POST works; SSE streaming is optional.
|
|
|
|
> `prompts/list` is **not supported**. If your MCP client calls it automatically (e.g. MAF's `MCPStreamableHTTPTool`), pass `load_prompts=False`.
|
|
|
|
## Tool naming
|
|
|
|
- **MCP-sourced tools** (`type: mcp`) are exposed as `{server_label}___{tool_name}` — **three underscores** (e.g. `myserver___get_info`).
|
|
- **All other tool types** use the entry's `name` field, or the default tool name if unset.
|
|
- **Tool Search** injects two meta-tools named `tool_search` and `call_tool`.
|
|
|
|
Each tool from `tools/list` includes a `_meta.tool_configuration` block with the `type` plus type-specific fields (e.g. `server_label`, `server_url`, `require_approval` for MCP).
|
|
|
|
## Testing the toolbox endpoint
|
|
|
|
Verify the MCP endpoint end-to-end with a bearer token + raw `tools/list` / `tools/call` — see [test-endpoint.md](test-endpoint.md).
|
|
|
|
## Troubleshooting (create / provision)
|
|
|
|
| Symptom | Likely cause |
|
|
|---------|--------------|
|
|
| `TOOLBOX_ENDPOINT` not set | Run `azd ai toolbox show` + `azd env set`. |
|
|
| Env var missing in deployed agent | Add to the agent service's `environmentVariables` in `azure.yaml`, `azd deploy`. |
|
|
| `403 Forbidden` on toolbox data-plane requests, including `POST /toolboxes` | Caller lacks `Foundry User` on the project — grant at project scope. |
|
|
| `403 Forbidden` on connection PUT | Caller lacks `Foundry Project Manager` (or `Cognitive Services Contributor`) on the project — grant at project scope. |
|
|
| 400 `Multiple tools without identifiers found` | Two unnamed tools (or duplicate `server_label`) — keep **at most one unnamed tool**; name each other. See [toolbox-azd.md § Multi-tool rule](toolbox-azd.md#multi-tool-rule). |
|
|
| `tools/list` returns zero | Version still provisioning, or tool type unavailable in region — wait ~10s, retry, or try another region. |
|
|
| `tools/list` zero for MCP/A2A only | Invalid/missing connection creds — verify `project_connection_id`; for MI auth, check RBAC on the target. |
|
|
| `tools/list` zero for OpenAPI only | Invalid OpenAPI spec — validate against 3.0/3.1; for MI auth, verify RBAC. |
|
|
|
|
For runtime/MCP-client errors (token scope, `prompts/list`, `require_approval`, tool-name prefixes), see [use-toolbox-in-hosted-agent.md § Troubleshooting](../../create/references/use-toolbox-in-hosted-agent.md#troubleshooting).
|