Skip to main content
Items marked (preview) in this article are currently in public preview. This preview is provided without a service-level agreement, and we don’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.
A custom code interpreter gives you full control over the runtime environment for agent-generated Python code. You can configure custom Python packages, compute resources, and Azure Container Apps environment settings. The code interpreter container exposes a Model Context Protocol (MCP) server. Use a custom code interpreter when the built-in Code Interpreter tool for agents doesn’t meet your requirements—for example, when you need specific Python packages, custom container images, or dedicated compute resources. For more information about MCP and how agents connect to MCP tools, see Connect to Model Context Protocol servers (preview).

​
Usage support

This article uses the Azure CLI and a runnable sample project. The following table shows SDK and setup support.
Microsoft Foundry supportPython SDKC# SDKJavaScript SDKJava SDKREST APIBasic agent setupStandard agent setup
✔️✔️✔️✔️✔️✔️-✔️
For the latest SDK and API support for agents tools, see Best practices for using tools in Microsoft Foundry Agent Service.

​
SDK support

The custom code interpreter uses the MCP tool type. Any SDK that supports MCP tools can create a custom code interpreter agent. The .NET SDK is currently in preview. For the infrastructure provisioning steps (Azure CLI, Bicep), see Create an agent with custom code interpreter.

​
Prerequisites

  • Azure CLI version 2.60.0 or later.
  • (Optional) uv for faster Python package management.
  • An Azure subscription and resource group with the following role assignments:
The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

​
Before you begin

This procedure provisions Azure infrastructure, including Azure Container Apps resources. Review your organization’s Azure cost and governance requirements before deploying.

​
Create an agent with custom code interpreter

The following steps show how to provision the infrastructure and create an agent that uses a custom code interpreter MCP server. The infrastructure setup applies to all languages. Language-specific code samples follow.

​
Register the preview feature

Register the MCP server feature for Azure Container Apps Dynamic Sessions: 
az feature register --namespace Microsoft.App --name SessionPoolsSupportMCP
az provider register -n Microsoft.App

​
Get the sample code

Clone the sample code in the GitHub repo and navigate to the samples/python/prompt-agents/code-interpreter-custom folder in your terminal.

​
Provision the infrastructure

To provision the infrastructure, run the following command by using the Azure CLI (az): 
az deployment group create \
    --name custom-code-interpreter \
    --subscription <your_subscription> \
    --resource-group <your_resource_group> \
    --template-file ./infra.bicep
Deployment can take up to one hour, depending on the number of standby instances you request. The dynamic session pool allocation is the longest step.

​
Configure and run the agent

Copy the .env.sample file from the repository to .env and populate the values from your deployment output. You can find these values in the Azure portal under the resource group. Install the Python dependencies by using uv sync or pip install. Finally, run ./main.py.

​
Verify your setup

After you’ve provisioned the infrastructure and run the sample:
  1. Confirm the Azure deployment completed successfully.
  2. Confirm the sample connects using the values in your .env file.
  3. In Microsoft Foundry, verify your agent calls the tool using tracing. For more information, see Best practices for using tools in Microsoft Foundry Agent Service.

​
Troubleshooting

IssueLikely causeResolution
Feature registration is still pendingThe az feature register command returns Registering state.Wait for registration to complete (can take 15-30 minutes). Check status with az feature show --namespace Microsoft.App --name SessionPoolsSupportMCP. Then run az provider register -n Microsoft.App again.
Deployment fails with permission errorMissing required role assignments.Confirm you have Foundry Owner and Container Apps ManagedEnvironment Contributor roles on the subscription or resource group.
Deployment fails with region errorThe selected region doesn’t support Azure Container Apps Dynamic Sessions.Try a different region. See Azure Container Apps regions for supported regions.
Agent doesn’t call the toolThe MCP connection isn’t configured correctly, or the agent instructions don’t prompt tool use.Use tracing in Microsoft Foundry to confirm tool invocation. Verify the MCP_SERVER_URL matches your deployed Container Apps endpoint. See Best practices.
MCP server connection timeoutThe Container Apps session pool isn’t running or has no standby instances.Check the session pool status in the Azure portal. Increase standbyInstanceCount in your Bicep template if needed.
Code execution fails in containerMissing Python packages in the custom container.Update your container image to include required packages. Rebuild and redeploy the container.
Authentication error connecting to MCP serverThe project connection credentials are invalid or expired.Regenerate the connection credentials and update the .env file. Verify the MCP_PROJECT_CONNECTION_ID format.

​
Limitations

The APIs don’t directly support file input or output, or the use of file stores. To get data in and out, you must use URLs, such as data URLs for small files and Azure Blob Service shared access signature (SAS) URLs for large files.

​
Security

If you use SAS URLs to pass data in or out of the runtime:
  • Use short-lived SAS tokens.
  • Don’t log SAS URLs or store them in source control.
  • Scope permissions to the minimum required (for example, read-only or write-only).

​
Clean up

To stop billing for provisioned resources, delete the resources created by the sample deployment. If you used a dedicated resource group for this article, delete the resource group.

​
Related content