> ## Documentation Index > Fetch the complete documentation index at: https://hobbyist-e43fa225.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Configure a custom code interpreter for agents > Configure a custom MCP-based code interpreter for Microsoft Foundry agents using Azure Container Apps Dynamic Sessions. Customize Python packages and compute resources. export const ZonePivot = ({group, options = [], defaultValue, label = "Choose an experience"}) => { const values = options.map(option => option.id); const optionKey = options.map(option => `${option.id}:${option.title}`).join("|"); const [activePivot, setActivePivot] = useState(defaultValue || values[0]); const slugify = value => value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, ""); const resolvePivot = () => { if (typeof window === "undefined") return defaultValue || values[0]; const params = new URLSearchParams(window.location.search); const requested = params.get("pivots"); if (requested) { const requestedIds = requested.split(",").map(value => value.trim()).filter(Boolean); const match = requestedIds.find(id => values.includes(id)); if (match) return match; } const hash = window.location.hash.replace(/^#/, ""); if (hash) { const match = options.find(option => option.id === hash || slugify(option.title) === hash); if (match) return match.id; } try { const stored = window.localStorage.getItem(`foundry-zone-pivot:${group}`); if (values.includes(stored)) return stored; } catch { return defaultValue || values[0]; } return defaultValue || values[0]; }; const publishPivotChange = value => { if (typeof window === "undefined") return; window.dispatchEvent(new CustomEvent("foundry-zone-pivot-change", { detail: { group, value } })); }; const syncTableOfContents = () => { if (typeof window === "undefined") return; window.requestAnimationFrame(() => { const toc = document.getElementById("table-of-contents-content"); if (!toc) return; const links = Array.from(toc.querySelectorAll('a[href^="#"]')); for (const link of links) { const item = link.closest("li"); const rawId = link.getAttribute("href")?.slice(1); if (!item || !rawId) continue; let id = rawId; try { id = decodeURIComponent(rawId); } catch {} item.style.display = document.getElementById(id) ? "" : "none"; } }); }; useEffect(() => { const resolvedPivot = resolvePivot(); setActivePivot(resolvedPivot); publishPivotChange(resolvedPivot); window.setTimeout(syncTableOfContents, 0); }, [group, defaultValue, values.join("|"), optionKey]); const selectPivot = value => { setActivePivot(value); if (typeof window !== "undefined") { try { window.localStorage.setItem(`foundry-zone-pivot:${group}`, value); } catch {} const url = new URL(window.location.href); const current = url.searchParams.get("pivots"); const preserved = current ? current.split(",").map(id => id.trim()).filter(id => id && !values.includes(id)) : []; url.searchParams.set("pivots", [...preserved, value].join(",")); window.history.replaceState(null, "", `${url.pathname}${url.search}${url.hash}`); } publishPivotChange(value); window.setTimeout(syncTableOfContents, 0); }; if (options.length < 2) return null; return
{label}
{options.map(option => { const selected = option.id === activePivot; return ; })}
; }; export const ZoneContent = ({group, value, options = [], values = [], defaultValue, children}) => { const optionKey = options.map(option => `${option.id}:${option.title}`).join("|"); const [activePivot, setActivePivot] = useState(defaultValue || values[0]); const slugify = value => value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, ""); const resolvePivot = () => { if (typeof window === "undefined") return defaultValue || values[0]; const params = new URLSearchParams(window.location.search); const requested = params.get("pivots"); if (requested) { const requestedIds = requested.split(",").map(value => value.trim()).filter(Boolean); const match = requestedIds.find(id => values.includes(id)); if (match) return match; } const hash = window.location.hash.replace(/^#/, ""); if (hash) { const match = options.find(option => option.id === hash || slugify(option.title) === hash); if (match) return match.id; } try { const stored = window.localStorage.getItem(`foundry-zone-pivot:${group}`); if (values.includes(stored)) return stored; } catch { return defaultValue || values[0]; } return defaultValue || values[0]; }; useEffect(() => { setActivePivot(resolvePivot()); }, [group, defaultValue, values.join("|"), optionKey]); useEffect(() => { const onPivotChange = event => { if (event.detail?.group === group && values.includes(event.detail.value)) { setActivePivot(event.detail.value); } }; window.addEventListener("foundry-zone-pivot-change", onPivotChange); return () => window.removeEventListener("foundry-zone-pivot-change", onPivotChange); }, [group, values.join("|")]); if (activePivot !== value) return null; return <>{children}; }; 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](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). 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](https://learn.microsoft.com/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](/agents/code-interpreter) 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)](/tools-and-knowledge/model-context-protocol). ## 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](/agents/tool-best-practice). ## 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](#create-an-agent-with-custom-code-interpreter). ## Prerequisites * [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) version 2.60.0 or later. * (Optional) [uv](https://docs.astral.sh/uv/getting-started/installation/) for faster Python package management. * An Azure subscription and resource group with the following role assignments: * [Foundry Owner](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles/ai-machine-learning#azure-ai-owner) > 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. * [Container Apps ManagedEnvironment Contributor](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles/containers#container-apps-managedenvironments-contributor) * An Azure AI Foundry SDK. See the [quickstart](/get-started/get-started-code) for installation. ## 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: ```console theme={null} 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](https://github.com/microsoft-foundry/foundry-samples) 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`): ```console theme={null} az deployment group create \ --name custom-code-interpreter \ --subscription \ --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`. ### Code example The following Python sample shows how to create an agent with a custom code interpreter MCP tool: ```python theme={null} from azure.identity import DefaultAzureCredential from azure.ai.projects import AIProjectClient from azure.ai.projects.models import PromptAgentDefinition, MCPTool # Format: "https://resource_name.ai.azure.com/api/projects/project_name" PROJECT_ENDPOINT = "your_project_endpoint" MCP_SERVER_URL = "https://your-mcp-server-url" # Optional: set to your project connection ID if your MCP server requires authentication MCP_CONNECTION_ID = "your-mcp-connection-id" # Create clients to call Foundry API project = AIProjectClient( endpoint=PROJECT_ENDPOINT, credential=DefaultAzureCredential(), ) openai = project.get_openai_client() # Configure the custom code interpreter MCP tool custom_code_interpreter = MCPTool( server_label="custom-code-interpreter", server_url=MCP_SERVER_URL, project_connection_id=MCP_CONNECTION_ID, ) # Create an agent with the custom code interpreter agent = project.agents.create_version( agent_name="CustomCodeInterpreterAgent", definition=PromptAgentDefinition( model="gpt-5-mini", instructions="You are a helpful assistant that can run Python code to analyze data and solve problems.", tools=[custom_code_interpreter], ), description="Agent with custom code interpreter for data analysis.", ) print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})") # Test the agent with a simple calculation response = openai.responses.create( input="Calculate the factorial of 10 using Python.", extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}}, ) print(f"Response: {response.output_text}") # Clean up project.agents.delete_version(agent_name=agent.name, agent_version=agent.version) print("Agent deleted") ``` ### Expected output When you run the sample, you see output similar to: ```console theme={null} Agent created (id: agent-xxxxxxxxxxxx, name: CustomCodeInterpreterAgent, version: 1) Response: The factorial of 10 is 3,628,800. I calculated this using Python's math.factorial() function. Agent deleted ``` ### Code example The following C# sample shows how to create an agent with a custom code interpreter MCP tool. For more information about working with MCP tools in .NET, see the [MCP tool sample](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/ai/Azure.AI.Extensions.OpenAI/samples/Sample19_MCP.md) in the Azure SDK for .NET repository on GitHub. ```csharp theme={null} using Azure.AI.Projects; using Azure.AI.Extensions.OpenAI; using Azure.Identity; // Format: "https://resource_name.ai.azure.com/api/projects/project_name" var projectEndpoint = "your_project_endpoint"; var mcpServerUrl = "https://your-mcp-server-url"; // Optional: set to your project connection ID if your MCP server requires authentication var mcpConnectionId = "your-mcp-connection-id"; // Create project client to call Foundry API AIProjectClient projectClient = new( endpoint: new Uri(projectEndpoint), tokenProvider: new DefaultAzureCredential()); // Create agent with custom code interpreter MCP tool // Code runs in a sandboxed Azure Container Apps session McpTool tool = ResponseTool.CreateMcpTool( serverLabel: "custom-code-interpreter", serverUri: new Uri(mcpServerUrl)); tool.ProjectConnectionId = mcpConnectionId; DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini") { Instructions = "You are a helpful assistant that can run Python code to analyze data and solve problems.", Tools = { tool } }; AgentVersion agent = projectClient.AgentAdministrationClient.CreateAgentVersion( agentName: "CustomCodeInterpreterAgent", options: new(agentDefinition)); Console.WriteLine($"Agent created: {agent.Name} (version {agent.Version})"); // Create a response using the agent ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agent.Name); ResponseResult response = responseClient.CreateResponse( new([ResponseItem.CreateUserMessageItem("Calculate the factorial of 10 using Python.")])); Console.WriteLine(response.GetOutputText()); // Clean up projectClient.AgentAdministrationClient.DeleteAgentVersion( agentName: agent.Name, agentVersion: agent.Version); Console.WriteLine("Agent deleted"); ``` ### Expected output ```console theme={null} Agent created: CustomCodeInterpreterAgent (version 1) The factorial of 10 is 3,628,800. Agent deleted ``` ### Code example The following TypeScript sample shows how to create an agent with a custom code interpreter MCP tool. For a JavaScript version, see the [MCP tool sample](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/ai/ai-projects/samples/v2-beta/javascript/agents/tools/agentMcp.js) in the Azure SDK for JavaScript repository on GitHub. ```typescript theme={null} import { DefaultAzureCredential } from "@azure/identity"; import { AIProjectClient } from "@azure/ai-projects"; // Format: "https://resource_name.ai.azure.com/api/projects/project_name" const PROJECT_ENDPOINT = "your_project_endpoint"; const MCP_SERVER_URL = "https://your-mcp-server-url"; export async function main(): Promise { // Create clients to call Foundry API const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential()); const openai = project.getOpenAIClient(); // Create agent with custom code interpreter MCP tool // The custom code interpreter uses require_approval: "never" because code // runs in a sandboxed Azure Container Apps session const agent = await project.agents.createVersion("CustomCodeInterpreterAgent", { kind: "prompt", model: "gpt-5-mini", instructions: "You are a helpful assistant that can run Python code to analyze data and solve problems.", tools: [ { type: "mcp", server_label: "custom-code-interpreter", server_url: MCP_SERVER_URL, require_approval: "never", }, ], }); console.log(`Agent created (name: ${agent.name}, version: ${agent.version})`); // Send a request to the agent const response = await openai.responses.create( { input: "Calculate the factorial of 10 using Python.", }, { body: { agent: { name: agent.name, type: "agent_reference" } }, }, ); console.log(`Response: ${response.output_text}`); // Clean up await project.agents.deleteVersion(agent.name, agent.version); console.log("Agent deleted"); } main().catch((err) => { console.error("The sample encountered an error:", err); }); ``` ### Expected output ```console theme={null} Agent created (name: CustomCodeInterpreterAgent, version: 1) Response: The factorial of 10 is 3,628,800. I calculated this using Python's math.factorial() function. Agent deleted ``` Add the dependency to your `pom.xml`: ```xml theme={null} com.azure azure-ai-agents 2.2.0 ``` ### Code example ```java theme={null} import com.azure.ai.agents.AgentsClient; import com.azure.ai.agents.AgentsClientBuilder; import com.azure.ai.agents.ResponsesClient; import com.azure.ai.agents.models.AgentReference; import com.azure.ai.agents.models.AgentVersionDetails; import com.azure.ai.agents.models.AzureCreateResponseOptions; import com.azure.ai.agents.models.McpTool; import com.azure.ai.agents.models.PromptAgentDefinition; import com.azure.identity.DefaultAzureCredentialBuilder; import com.openai.models.responses.Response; import com.openai.models.responses.ResponseCreateParams; import java.util.Collections; public class CustomCodeInterpreterExample { public static void main(String[] args) { // Format: "https://resource_name.ai.azure.com/api/projects/project_name" String projectEndpoint = "your_project_endpoint"; String mcpServerUrl = "https://your-mcp-server-url"; // Optional: set to your project connection ID if your MCP server requires authentication String mcpConnectionId = "your-mcp-connection-id"; // Create clients to call Foundry API AgentsClientBuilder builder = new AgentsClientBuilder() .credential(new DefaultAzureCredentialBuilder().build()) .endpoint(projectEndpoint); AgentsClient agentsClient = builder.buildAgentsClient(); ResponsesClient responsesClient = builder.buildResponsesClient(); // Create custom code interpreter MCP tool // Uses require_approval: "never" because code runs in a sandboxed Container Apps session McpTool customCodeInterpreter = new McpTool("custom-code-interpreter") .setServerUrl(mcpServerUrl) .setProjectConnectionId(mcpConnectionId) .setRequireApproval("never"); PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-5-mini") .setInstructions("You are a helpful assistant that can run Python code to analyze data and solve problems.") .setTools(Collections.singletonList(customCodeInterpreter)); AgentVersionDetails agent = agentsClient.createAgentVersion( "CustomCodeInterpreterAgent", agentDefinition); System.out.printf("Agent created: %s (version %s)%n", agent.getName(), agent.getVersion()); // Create a response AgentReference agentReference = new AgentReference(agent.getName()) .setVersion(agent.getVersion()); Response response = responsesClient.createAzureResponse( new AzureCreateResponseOptions().setAgentReference(agentReference), ResponseCreateParams.builder() .input("Calculate the factorial of 10 using Python.")); System.out.println("Response: " + response.output()); // Clean up agentsClient.deleteAgentVersion(agent.getName(), agent.getVersion()); System.out.println("Agent deleted"); } } ``` ### Expected output ```console theme={null} Agent created: CustomCodeInterpreterAgent (version 1) Response: The factorial of 10 is 3,628,800. Agent deleted ``` ### Prerequisites Set these environment variables: * `FOUNDRY_PROJECT_ENDPOINT`: Your project endpoint URL. * `AGENT_TOKEN`: A bearer token for Foundry. Get an access token: ```bash theme={null} export AGENT_TOKEN=$(az account get-access-token --scope "https://ai.azure.com/.default" --query accessToken -o tsv) ``` ### Code example #### 1. Create an agent with custom code interpreter ```bash theme={null} curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $AGENT_TOKEN" \ -d '{ "name": "CustomCodeInterpreterAgent", "definition": { "kind": "prompt", "model": "", "instructions": "You are a helpful assistant that can run Python code to analyze data and solve problems.", "tools": [ { "type": "mcp", "server_label": "custom-code-interpreter", "server_url": "", "project_connection_id": "", "require_approval": "never" } ] } }' ``` #### 2. Create a response ```bash theme={null} curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $AGENT_TOKEN" \ -d '{ "agent_reference": {"type": "agent_reference", "name": "CustomCodeInterpreterAgent"}, "input": "Calculate the factorial of 10 using Python." }' ``` #### 3. Clean up ```bash theme={null} curl -X DELETE "$FOUNDRY_PROJECT_ENDPOINT/agents/CustomCodeInterpreterAgent?api-version=v1" \ -H "Authorization: Bearer $AGENT_TOKEN" ``` ### Expected output ```json theme={null} { "id": "resp_xxxxxxxxxxxx", "output": [ { "type": "message", "role": "assistant", "content": [ { "type": "output_text", "text": "The factorial of 10 is 3,628,800." } ] } ] } ``` ## 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](/agents/tool-best-practice). ## 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. | Confirm you have **Foundry Owner** and **Container Apps ManagedEnvironment Contributor** roles on the subscription or resource group. | | 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](https://learn.microsoft.com/azure/container-apps/overview#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](/agents/tool-best-practice). | | 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 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)](/tools-and-knowledge/model-context-protocol) * [Best practices for using tools in Microsoft Foundry Agent Service](/agents/tool-best-practice) * [Azure Container Apps Dynamic Sessions](https://learn.microsoft.com/azure/container-apps/sessions) * [Session pools with custom containers](https://learn.microsoft.com/azure/container-apps/session-pool#custom-container-pool) * [Azure Container Apps environment](https://learn.microsoft.com/azure/container-apps/environment) * [Install the Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) * [Code Interpreter tool for agents](/agents/code-interpreter)