Implementation | Optional module: API Center private tool catalog to Foundry Toolbox

Chapter 5 of 6

Implement#

1. Complete the catalog record#

Fill catalog-toolbox-binding.json with the approved scope, source record, owner roles, Foundry names, and restore owner. Use a new Toolbox name reserved for this MCP connection.

Calculate the normalized endpoint digest. Trim a final / before hashing.

PowerShell

$mcpEndpoint = Read-Host "Approved MCP endpoint"
$normalizedEndpoint = $mcpEndpoint.TrimEnd("/")
$endpointHash = [Convert]::ToHexString(
    [Security.Cryptography.SHA256]::HashData(
        [Text.Encoding]::UTF8.GetBytes($normalizedEndpoint)
    )
).ToLowerInvariant()
$endpointHash

Bash

read -r -p "Approved MCP endpoint: " mcp_endpoint
normalized_endpoint=${mcp_endpoint%/}
printf '%s' "$normalized_endpoint" | sha256sum | cut -d' ' -f1

Store the endpoint in toolbox-version.json and its digest in the catalog record. Keep the filled files in the approved private configuration store.

2. Configure the catalog item in Foundry Tools#

In the Azure portal, open the exact API Center resource. Confirm the MCP server's authorization configuration and its Details > Versions > Manage access (preview) settings.

Then open the intended project in the Microsoft Foundry portal:

Go to Build > Tools.
Find the private tool catalog by the API Center name.
Select the MCP server record in API Center.
Review its setup requirements and configure it for the project.
Record the resulting project connection name in both artifacts.

This is the current documented portal step that connects the catalog record to the project. If the portal does not expose the record or cannot create a connection that matches the approved authentication mode, stop.

3. Run preflight#

PowerShell

$projectEndpoint = "https://<foundry-account>.services.ai.azure.com/api/projects/<project>"
$approvedTargetScope = "<approved-nonproduction-scope>"
.\scripts\preflight.ps1 `
  -ProjectEndpoint $projectEndpoint `
  -ApprovedTargetScope $approvedTargetScope

Bash

project_endpoint="https://<foundry-account>.services.ai.azure.com/api/projects/<project>"
approved_target_scope="<approved-nonproduction-scope>"
./scripts/preflight.sh \
  --project-endpoint "$project_endpoint" \
  --approved-target-scope "$approved_target_scope"

Preflight checks the exact scope, preview approval, portal discovery decision, endpoint digest, project connection, one-tool allow list, approval setting, implementation marker, and Toolbox name collision.

Microsoft Foundry has no read-only deployment preview for Toolbox version creation. Preflight says so, inspects the existing project connection, and requires the dedicated Toolbox name to be absent before the POST. It also names the Python command for the confirmation check: python, or the Windows py launcher when python does not resolve.

4. Create the first Toolbox version#

Use the Microsoft Foundry v1 data-plane route. The first version of a new Toolbox becomes the default version.

PowerShell

$binding = Get-Content .\artifacts\governance\catalog-toolbox-binding.json -Raw |
  ConvertFrom-Json
$payload = Get-Content .\artifacts\toolbox\toolbox-version.json -Raw
$token = az account get-access-token `
  --resource https://ai.azure.com `
  --query accessToken `
  --output tsv
$createUri = "$projectEndpoint/toolboxes/$($binding.foundryBinding.toolboxName)/versions?api-version=v1"
$created = Invoke-RestMethod `
  -Method Post `
  -Uri $createUri `
  -Headers @{ Authorization = "Bearer $token" } `
  -ContentType "application/json" `
  -Body $payload
$toolboxVersion = [string]$created.version
$versionEndpoint = "$projectEndpoint/toolboxes/$($binding.foundryBinding.toolboxName)/versions/$toolboxVersion/mcp?api-version=v1"

Bash

binding_path="./artifacts/governance/catalog-toolbox-binding.json"
payload_path="./artifacts/toolbox/toolbox-version.json"
toolbox_name=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["foundryBinding"]["toolboxName"])' "$binding_path")
token=$(az account get-access-token --resource https://ai.azure.com --query accessToken --output tsv)
create_uri="$project_endpoint/toolboxes/$toolbox_name/versions?api-version=v1"
created=$(curl --fail --silent --show-error \
  --request POST \
  --url "$create_uri" \
  --header "Authorization: Bearer $token" \
  --header "Content-Type: application/json" \
  --data-binary "@$payload_path")
toolbox_version=$(printf '%s' "$created" | python3 -c 'import json,sys; print(json.load(sys.stdin)["version"])')
version_endpoint="$project_endpoint/toolboxes/$toolbox_name/versions/$toolbox_version/mcp?api-version=v1"
unset token

Do not print or retain the access token. Record the returned version number in observedState.toolboxVersion.

5. Hand the consumer endpoint to agent owners#

The reusable consumer endpoint omits /versions/{version} and always serves the Toolbox default_version:

{project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1

Pass it to agent teams through the approved runtime configuration path. The release owner decides when an agent can use the Toolbox and how the runtime presents approval requests.