Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Use Azure Policy in Microsoft Foundry to govern saved toolbox configurations and prompt agents without the Microsoft Copilot harness. Use project tool controls to restrict runtime tool use. Keep their allow lists aligned, and verify saving and running separately.
This guide covers native tool governance. It doesn't require an AI gateway. For gateway routing, rate limits, and IP restrictions on MCP traffic, see Govern MCP tools by using an AI gateway.
Prerequisites
- A Foundry project and its Azure resource ID. Use a test project before applying restrictions to production workloads.
- The Owner or Resource Policy Contributor role at the scope where you assign Azure Policy. For more information, see Azure Policy and Azure RBAC.
- Permission to read and update the Foundry project through Azure Resource Manager. Policy assignment permissions and runtime tool permissions are separate.
- For the REST API or Terraform procedure, Azure CLI and
jqin Bash, including Azure Cloud Shell. Sign in to the subscription that contains your project. - Terraform if you use the Terraform option. The example uses the AzAPI provider to update an existing project.
- An agent or toolbox with working tool access for verification. A governance allow list doesn't grant access to data, credentials, or external services.
Understand the two controls
Azure Policy and project tool controls have different settings and enforcement points:
- Azure Policy evaluates supported prompt agent and toolbox configurations against your organization's approved tools. The
Denyeffect blocks noncompliant create or update operations.Auditreports noncompliance without blocking those operations. - Project tool controls are stored in the project's
properties.toolControlsproperty and restrict runtime tool use. SetdefaultActiontoDenyand list the permitted tools inallowedTools.
These Azure Policy checks currently apply to toolboxes and prompt agents that use the Responses API without the Microsoft Copilot harness.
Hosted agents run your code, which this policy doesn't inspect, regardless of the harness or framework you use. Govern their Foundry tool access through the toolboxes they call. Check each toolbox's compliance status and configure project toolControls to restrict runtime tool use through the toolbox. A noncompliant toolbox doesn't block hosted-agent creation.
The project's toolControls.allowedTools list is a runtime control, not a validation rule for agent or toolbox create, read, update, or delete (CRUD) operations. For example, with defaultAction: Deny and only file_search in allowedTools, you can still save an agent or toolbox configured with web_search unless an applicable Azure Policy blocks the save. Project controls block runtime use of web_search after the settings propagate. Saving a tool configuration doesn't invoke the tool.
Assigning an Azure Policy doesn't populate or rewrite toolControls. Updating toolControls doesn't create or change a policy assignment. The project property isn't an Azure Policy definition.
If toolControls is absent, this feature doesn't restrict the project's runtime tool use. Other controls, including applicable policies, authentication, and network restrictions, still apply.
Treat these controls as restrictions on tools processed by Foundry, not as a network firewall. Don't rely on them to govern arbitrary outbound calls from hosted-agent code. Use network isolation and service-specific authorization for those calls.
Assign an Azure Policy for tools
The built-in policy [Preview]: Microsoft Foundry agents and toolboxes should only use approved tools defines an allow list. It supports Audit, Deny, and Disabled, and defaults to Audit.
Disabled skips evaluation for that policy assignment. It doesn't disable project tool controls.
Start with Audit to assess the impact on supported agent and toolbox configurations. Use Deny to block noncompliant create and update operations for those resources.
Assign the policy at the Foundry account scope whenever possible. Each assignment has a limit on the number of agents and toolboxes it can evaluate. Broader scopes can reach this limit and leave some resources unevaluated.
A request must satisfy every applicable, enforced Deny assignment (AND logic). If any one denies the create or update operation, another assignment can't override the denial. For resources that need an exception, see Azure Policy exemptions.
Azure Policy changes can take up to 30 minutes to take effect. Compliance reporting is separate: results can take up to 12 hours to appear or update.
- In the Azure portal, open Policy, and then select Definitions.
- Search for [Preview]: Microsoft Foundry agents and toolboxes should only use approved tools. Confirm that its definition ID ends in
e7352ad2-6c86-4a07-9573-47f67b557ba8, open the definition, and select Assign. - Select the Foundry account as the assignment scope whenever possible, and configure any required exclusions.
- On Parameters, configure the effect and the tool restrictions:
- Approved Tool Types (
approvedToolTypes): Tool type identifiers from the tool type catalog. - Approved MCP Endpoints (
approvedMcpEndpoints): Approved MCP server URLs or endpoint patterns. - Approved MCP Connectors (
approvedMcpConnectors): Approved MCP connector identifiers.
- Approved Tool Types (
- Review the assignment and create it.
- Verify enforcement after the policy propagation delay. Review the assignment's compliance results separately when they're available.
For the full assignment procedure, see Create a policy assignment in the Azure portal.
For policy assignment steps, select the Azure portal pivot. The REST API and Terraform procedures in this article update project runtime controls, not policy assignments.
Choose approved tool types
Use the tool type identifiers in the following catalog for approvedToolTypes. It's a reference list, not a recommended allow list.
[
"a2a",
"azure_ai_search",
"azure_function",
"bing_custom_search",
"bing_grounding",
"browser_automation",
"code_interpreter",
"computer_use",
"custom",
"fabric_dataagent",
"fabric_iq",
"file_search",
"function",
"image_generation",
"mcp",
"memory_search",
"openapi",
"reminder",
"sharepoint_grounding",
"shell",
"toolbox_search",
"web_search",
"work_iq"
]
Select only the types your organization approves. Availability differs by API version, model, and agent or toolbox integration.
This catalog describes policy parameter values. It doesn't mean every identifier is supported by project toolControls or every runtime path. In particular, approving mcp by type has broader scope than approving an individual MCP target.
Restrict MCP targets
The approved-tools policy accepts a tool when its type, MCP endpoint, or MCP connector matches an approved entry. These are alternative matches, not requirements that all match.
To restrict MCP access to particular servers, add their URLs to approvedMcpEndpoints or their connector identifiers to approvedMcpConnectors. Don't add the broad mcp type to approvedToolTypes, because that action approves MCP tools by type without requiring an endpoint or connector match.
For endpoint-based restrictions, add the toolbox's MCP endpoint to approvedMcpEndpoints in each applicable assignment. Approve the toolbox endpoint separately from the tools inside it.
MCP endpoint patterns in Azure Policy are case-insensitive. Each pattern supports at most one * wildcard; regular expressions and other pattern-matching syntax aren't supported.
For example, https://mcp.contoso.com/* matches endpoints under that host. A pattern such as https://*.contoso.com/* isn't supported because it contains two wildcards. Use the narrowest pattern that meets your needs.
Configure project tool controls
Project toolControls has no audit mode. Test the complete allow list in a test project before applying it to a project with running workloads. Changes can take several minutes to take effect.
Include all MCP endpoints used by your tools in allowedTools to avoid unintentionally blocking tool access.
Read the current project configuration before changing it. The REST API and Terraform examples permit only file_search through the project's tool controls. They don't configure the tool on an agent or grant access to a vector store.
The preceding Azure portal procedure assigns Azure Policy; it doesn't update the project's runtime allow list. Select the REST API or Terraform pivot for those updates.
Read the current project configuration
Set the project identifiers and read the project. Replace the placeholders with your values, and run the commands in this procedure in the same Bash session.
SUBSCRIPTION_ID="<subscription-id>"
RESOURCE_GROUP="<resource-group-name>"
FOUNDRY_RESOURCE="<foundry-resource-name>"
PROJECT_NAME="<project-name>"
PROJECT_ID="/subscriptions/$SUBSCRIPTION_ID"
PROJECT_ID+="/resourceGroups/$RESOURCE_GROUP"
PROJECT_ID+="/providers/Microsoft.CognitiveServices/accounts"
PROJECT_ID+="/$FOUNDRY_RESOURCE/projects/$PROJECT_NAME"
PROJECT_URL="https://management.azure.com${PROJECT_ID}"
PROJECT_URL+="?api-version=2026-09-15-preview"
az rest --method get --url "$PROJECT_URL" \
--output json > project-before.json
jq '.properties.toolControls' project-before.json
The command displays the stored project controls, or null if the property is absent. Keep project-before.json as a record of the previous configuration.
Reference: az rest.
Configure project tool controls with REST
Create a file named
tool-controls.jsonwith the following content:{ "properties": { "toolControls": { "defaultAction": "Deny", "allowedTools": [ { "type": "file_search" } ] } } }This is the intended replacement allow list, not an instruction to append one entry. Include every tool that the project needs before you apply it. Preserve any other existing
toolControlssettings in your request.Update the project with a
PATCHrequest. Use the ETag from the project read to avoid overwriting a concurrent change.ETAG=$(jq -r '.etag // .eTag // empty' project-before.json) if [ -z "$ETAG" ]; then printf 'No project ETag returned. Stop without updating.\n' >&2 exit 1 fi az rest --method patch --url "$PROJECT_URL" \ --headers "Content-Type=application/json" "If-Match=$ETAG" \ --body @tool-controls.jsonIf the update fails, stop and inspect the error. For a concurrent modification, read the project again and reconcile the changes before submitting a new request.
Reference: az rest.
After the update, verify the stored project controls.
Update project tool controls with Terraform
Use azapi_update_resource to manage toolControls on an existing project without creating or replacing the project. This option changes project controls, not Azure Policy assignments.
Choose either REST or Terraform to manage these settings. Don't manage the same property through multiple Terraform resources.
Create
main.tfwith the following content:terraform { required_providers { azapi = { source = "Azure/azapi" version = "~> 2.13.0" } } } variable "subscription_id" { type = string } variable "tenant_id" { type = string } variable "project_resource_id" { type = string } provider "azapi" { subscription_id = var.subscription_id tenant_id = var.tenant_id use_cli = true use_msi = false use_oidc = false skip_provider_registration = true } resource "azapi_update_resource" "tool_controls" { type = "Microsoft.CognitiveServices/accounts/projects@2026-09-15-preview" resource_id = var.project_resource_id body = { properties = { toolControls = { defaultAction = "Deny" allowedTools = [ { type = "file_search" } ] } } } ignore_missing_property = false response_export_values = ["properties.toolControls"] } output "tool_controls" { value = azapi_update_resource.tool_controls.output.properties.toolControls }Reference: azapi_update_resource.
This example replaces the project allow list with
file_search. Include every required tool and preserve any other existingtoolControlssettings before applying it. For MCP entries, use a concreteserverUrlorconnectorId.Create
terraform.tfvarswith your project details:subscription_id = "<subscription-id>" tenant_id = "<tenant-id>" project_resource_id = "<full-project-resource-id>"Reference: Terraform input variables.
Use the full Azure resource ID, not the project endpoint. Confirm that your Azure CLI sign-in and the supplied subscription and tenant match the project.
Initialize the provider and review a saved plan:
terraform init terraform fmt -check terraform validate terraform plan -out=tool-controls.tfplanReference: terraform plan.
Confirm that the plan targets the intended existing project and changes only the requested controls. Terraform can show the update resource as an addition to its state; this doesn't mean it creates an Azure project.
Apply the saved plan and inspect the resulting controls:
terraform apply tool-controls.tfplan terraform output -json tool_controls terraform plan -detailed-exitcodeReference: terraform apply and terraform output.
The output contains
defaultAction: Denyand anallowedToolsarray containing onlyfile_search. A second plan should report no changes and return exit code0. After applying the plan, verify the stored project controls.
Destroying an azapi_update_resource removes it from Terraform state. It doesn't delete the Azure project, remove the controls, or restore their previous values. To change or restore the controls, explicitly apply the desired configuration; don't use terraform destroy as a rollback.
Verify stored project controls
Wait for the project update to complete, and then read back the stored configuration:
az rest --method get --url "$PROJECT_URL" --output json \
--query "properties.{state:provisioningState,toolControls:toolControls}"
If provisioning is still in progress, repeat the read. If provisioning fails, stop and inspect the operation error. Confirm that the state is Succeeded and that the stored allow list matches your intended configuration.
An accepted update isn't proof that runtime enforcement has propagated. Allow several minutes for toolControls changes to take effect before checking runtime behavior.
Reference: az rest.
Add an MCP server to the runtime allow list
For an MCP server, add a concrete target to the allowedTools array. Use the server URL that the agent or toolbox uses:
{
"type": "mcp",
"serverUrl": "https://mcp.contoso.com/mcp"
}
For a connector-based MCP tool, use its connector identifier instead:
{
"type": "mcp",
"connectorId": "<approved-connector-id>"
}
These fragments are individual allowedTools entries, not complete project update requests. Each MCP entry must specify exactly one of serverUrl or connectorId. A bare {"type": "mcp"} entry isn't valid.
Use actual server URLs or connector identifiers in the project configuration. Keep Azure Policy endpoint patterns separate from these concrete project entries.
For a toolbox accessed through MCP, include its endpoint, its required tools, and every MCP endpoint those tools use in allowedTools. Allowing an inner tool doesn't automatically approve the outer MCP connection.
Compare expected policy behavior
The following table distinguishes approved-tools policy evaluation from project runtime controls. Project tool controls don't validate agent or toolbox CRUD operations.
In the agent/toolbox columns, agent means a prompt agent that uses the Responses API without the Copilot harness. Copilot-harness prompt agents aren't currently evaluated. For hosted agents, the policy evaluates the toolboxes they use, not the hosted-agent code or creation.
These scenarios assume valid requests, the required permissions, and propagated settings. For Deny, they also assume enforcement is enabled.
| Configuration | Existing agent or toolbox versions | Agent or toolbox create or update | Runtime |
|---|---|---|---|
| Project controls only | No policy evaluation. | Allowed; no project-control check. | Project controls allow or deny tool use. |
Approved-tools policy with Deny |
Definition mismatches are reported; versions aren't rewritten. | Noncompliant writes are denied. | Project controls allow or deny tool use. |
Approved-tools policy with Audit |
Definition mismatches are reported; versions aren't rewritten. | Allowed; policy mismatches are audited, not denied. | Project controls allow or deny tool use. |
Audit and Disabled don't override project restrictions. The policy's compliance status doesn't itself block runtime tool calls. Runtime uses the project's stored tool controls, including for inline tool definitions and previously saved agent versions.
Existing versions are immutable. To change a definition, create a compliant version rather than rewriting the old one. For a toolbox, you can promote the compliant version to the default. Changing the default doesn't change retained versions or clients pinned to them.
Delete unused versions
Delete unused versions as part of routine maintenance for all agents and toolboxes, even when project tool controls aren't configured. Keep versions that active applications or rollback plans still need.
For guidance, see Agent Service version limits and Delete a toolbox version.
Verify saving and running separately
Use a test project and tools that don't make unwanted changes to external systems. For save-time checks, use a toolbox or a prompt agent without the Copilot harness. Check both the configuration and runtime paths after policy and project changes propagate.
- Read the approved-tools policy assignments at the project's scope, including inherited assignments. Confirm the definition ID,
approvedToolTypesand MCP parameters, effects, and enforcement settings. - Read the project's
toolControlsand confirm that the required runtime tools are listed. - Save an agent or toolbox version with an approved tool. Confirm that the save succeeds.
- With an enforced
Denypolicy, try to save a version containing a tool outside the policy's approved set. Confirm that the save is blocked. - Run an agent that uses a tool allowed by the project configuration. Confirm that it can use the tool, with its normal authentication and permissions.
- In the test project, use a tool that Azure Policy permits but project controls exclude. Confirm that a new agent or toolbox save succeeds, but runtime use of that tool is blocked.
- Test a tool excluded by project controls in two configurations: no agent/toolbox policy, and an
Auditassignment. Saves should succeed; runtime access should remain blocked. - Test an existing saved version after restricting its tool in project controls. Confirm that runtime access is blocked without rewriting the saved version.
Don't treat a successful save, a compliant policy result, or a successful project update as proof that an agent can run. Check the actual runtime path your application uses.
Allow up to 30 minutes for policy changes to take effect. Changes to toolControls can take several minutes, including when you restore runtime access.
Troubleshoot tool governance
Identify whether the failure occurs while saving a configuration or running an agent before changing either control. The save-time policy examples apply to toolboxes and prompt agents without the Copilot harness.
A tool runs, but you can't save a new agent version
An administrator can tighten the agent/toolbox policy without changing project controls. If project controls permit a tool outside the policy's approved set, an inline runtime request or existing version can use it. Saving a new version with that tool is blocked by the policy's Deny effect.
Review the policy named in the save error and compare it with the project's allow list. Work with the administrator to align the project configuration and agent definition with the policy. Don't assume that assigning a policy automatically changes existing runtime controls.
An agent version saves, but the runtime request is blocked
A new agent or toolbox version can pass Azure Policy checks even when its tools aren't in toolControls.allowedTools. For example, the policy permits web_search, but the project allows only file_search. The save succeeds, but runtime web search is blocked.
The same situation applies to existing versions after project controls change. Project controls don't reject or rewrite saved definitions.
Remove the excluded tool from the agent or ask an authorized project administrator to update the runtime allow list within the organization's approved configuration.
An MCP tool is blocked even though its inner tool is allowed
Check the MCP server URL or connector identifier on the agent's tool configuration. For a toolbox accessed through MCP, check its endpoint, its required tools, and every MCP endpoint those tools use. Add any missing required entries to toolControls.allowedTools rather than broadly allowing MCP access.
A policy reports noncompliance but doesn't block a save
Check the agent type first. These policy checks don't currently evaluate prompt agents that use the Copilot harness. For a hosted agent, test the toolbox configuration rather than hosted-agent creation.
For supported types, check the policy's effect and enforcement mode. Audit reports noncompliance; it doesn't block the operation. Confirm that the assignment applies to the intended scope and that policy changes have propagated.
Specific tool type or MCP endpoint still saves after you assign a Deny policy
First, identify which setting you changed. Project toolControls doesn't block saves, even when defaultAction is Deny. Test runtime tool use to verify that control.
For an Azure Policy assignment, inspect its definition ID and parameters. The approved-tools definition uses approvedToolTypes. Omit web_search from the approved list to make a configuration containing that tool noncompliant.
Five minutes isn't enough to rule out policy propagation. Allow up to 30 minutes, confirm the assignment's scope and enforcement mode, and retry with a toolbox or a prompt agent without the Copilot harness. Compliance reports can take up to 12 hours to update; that reporting delay is separate from enforcement.
If a new toolbox version containing web_search still saves after an applicable, enforced Deny assignment has propagated, that isn't explained by the hosted-agent or Copilot-harness exclusions. Capture the policy definition and assignment IDs, target resource ID, and save request details for support to investigate.
A permitted tool still fails
An allow list doesn't grant permissions or configure connectivity. Check the tool's connection, credentials, data access, and network settings. For MCP authentication, see Set up authentication for MCP tools.
Related content
Use these guides to configure tool access and complementary controls: