Configure a custom code interpreter for agents

Learn how to configure a custom MCP-based code interpreter for Foundry Agent Service by using Azure Container Apps Dynamic Sessions.

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).

Consider adding this tool using a toolbox. By using a toolbox, you are able to reuse the tool across agents and runtimes, as well as centralizing credential management, versioning, and policy enforcement through a managed MCP endpoint. See the toolbox quickstart.

Prerequisites

• Azure CLI version 2.60.0 or later.
• Python 3.12 or later for the maintained sample project.
• (Optional) uv for faster Python package management.
• An Azure subscription and resource group with the following role assignments:
  • Foundry User on the Foundry project for configuring and running the agent after provisioning.

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.

• Foundry Owner on the target resource group only while the sample deployment creates the Foundry resources and project connection.
• Container Apps ManagedEnvironment Contributor on the target resource group only while the sample deployment creates the Container Apps environment.

Activate the provisioning roles just in time through Microsoft Entra Privileged Identity Management (PIM), and deactivate them after deployment. Day-to-day agent developers and runtime users don’t need these provisioning roles.

• A Microsoft Foundry SDK. See the quickstart for installation.
• A region supported by both Foundry Agent Service and Azure Container Apps Dynamic Sessions. See Azure Container Apps Dynamic Sessions regions.

Usage support

This article uses the Azure CLI and a runnable sample project.

The following table shows SDK and setup support.

Microsoft Foundry support	Python SDK	C# SDK	JavaScript SDK	Java SDK	REST API	Basic agent setup	Standard 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.

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

The maintained direct-agent sample stores the session pool MCP endpoint in the project connection. Toolbox definitions also require the endpoint as server_url. Add this output to the cloned infra.bicep file:

output MCP_SERVER_URL string = sessionPool.properties.mcpServerSettings.mcpServerEndpoint

Don’t use poolManagementEndpoint. That value is the Dynamic Sessions management endpoint, not the MCP server endpoint.

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. Map the Bicep deployment outputs to the matching environment variables:

Bicep output	Environment variable	Used for
AZURE_AI_PROJECT_ENDPOINT	AZURE_AI_PROJECT_ENDPOINT	Foundry project endpoint.
AZURE_AI_CONNECTION_ID	AZURE_AI_CONNECTION_ID	Project connection whose target is the custom code interpreter MCP server.
MCP_SERVER_URL	MCP_SERVER_URL	Session pool MCP endpoint required by toolbox definitions.
AZURE_AI_MODEL_DEPLOYMENT_NAME	AZURE_AI_MODEL_DEPLOYMENT_NAME	Agent model deployment.

The inline examples use PROJECT_ENDPOINT for AZURE_AI_PROJECT_ENDPOINT and MCP_CONNECTION_ID for AZURE_AI_CONNECTION_ID. The maintained direct-agent sample resolves the MCP target through the project connection and uses https://localhost as a required placeholder URL. For a toolbox, set MCP_SERVER_URL to the mcpServerEndpoint output because MCPToolboxTool requires server_url or connector_id even when you also provide a project connection.

Install the Python dependencies and run the maintained sample with one of these command pairs:

uv sync
uv run ./main.py

Or create a virtual environment and install the checked-in requirements:

python -m venv .venv
./.venv/bin/pip install -r requirements.txt
./.venv/bin/python ./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

Issue	Likely cause	Resolution
Feature registration is still pending	The 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 error	Missing required role assignments.	For infrastructure deployment, activate Foundry Owner and Container Apps ManagedEnvironment Contributor on the target resource group through Microsoft Entra PIM. Deactivate them after deployment. For agent operations, confirm you have Foundry User on the Foundry project.
Deployment fails with region error	The 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 tool	The 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 timeout	The 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 container	Missing Python packages in the custom container.	Update your container image to include required packages. Rebuild and redeploy the container.
Authentication error connecting to MCP server	The 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

Treat generated code and its dependencies as untrusted. Use an approved base image and package allow list, run with the minimum required compute and permissions, and restrict outbound network access to required destinations. Don’t mount sensitive data or production credentials into the session.

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

• Connect to Model Context Protocol servers (preview)
• Azure Container Apps Dynamic Sessions
• Code Interpreter tool for agents