Chapter 2 of 6
Architecture at a glance#
The flow moves from API Center through the Foundry project connection to the runtime endpoint:
- The API catalog owner keeps the MCP server record in API Center, including its version, deployment, access, and authentication metadata.
- The Foundry tool owner opens the intended project, goes to Build > Tools, finds the private catalog by its API Center name, selects the MCP server record in API Center, and completes its project connection.
- The Toolbox deployment process creates an immutable version from
toolbox-version.json. The version refers to that project connection, exposes the approved tool, and requires approval for every call. - Agent teams consume the unversioned Toolbox endpoint. The implementation check uses the version-specific endpoint so it can inspect the exact created version.
The repository stores the catalog record and Toolbox version payload. API Center, the project connection, and Toolbox hold live state. The endpoint hash links the API Center deployment to the Toolbox payload without storing the endpoint in the governance record.
Design choices and tradeoffs#
| Decision | Chosen approach | Benefits | Costs and limitations |
|---|---|---|---|
| Catalog source | The MCP server record in API Center | Reuses the API Center inventory and owner metadata | The Foundry Tools private catalog is public preview and portal-led |
| Toolbox scope | A new dedicated Toolbox | Gives agents a stable consumer endpoint and keeps this change isolated | A separate Toolbox adds a managed object and owner |
| Tool exposure | The allowed_tools list contains one entry | Limits the Toolbox to the approved tool and makes mismatches visible | A tool rename requires a new Toolbox version |
| Approval | require_approval set to always | Agent runtimes receive the requirement with the tool metadata | The runtime must still present and enforce the approval interaction |
| Validation | tools/list against the version-specific endpoint | Checks the immutable version before agent reuse | It confirms discovery and approval metadata, not business behavior |
Architecture guidance#
Use Microsoft’s private tool catalog guidance for the current Azure API Center registration, authorization, access, and Build > Tools discovery path. The page marks the feature as public preview and notes that Azure RBAC changes can take up to 24 hours to appear.
Use Create and manage a toolbox in Foundry for Toolbox versioning, the v1 data-plane route, the default and version-specific MCP endpoints, and the tools/list check. A Toolbox version is immutable. The first version of a new Toolbox becomes its default version.
The MCP tool guidance defines project connections, allowed_tools, approval settings, and the Toolbox reuse pattern. Treat remote server tool metadata and results as untrusted input, even when the catalog record is approved.