Skip to main content
Connect your Foundry agents to Model Context Protocol (MCP) servers by using the MCP tool. This connection extends agent capabilities with external tools and data sources. By connecting to remote MCP server endpoints, your agent’s Foundry model can access tools hosted by developers and organizations that MCP-compatible clients like Foundry Agent Service can use. MCP is an open standard that defines how applications provide tools and contextual data to large language models (LLMs). It enables consistent, scalable integration of external tools into model workflows. In this article, you learn how to:
  • Add a remote MCP server as a tool.
  • Authenticate to an MCP server by using a project connection.
  • Review and approve MCP tool calls.
  • Troubleshoot common MCP integration issues.
For conceptual details about how MCP integration works, see How it works.

​
Usage support

The following table shows SDK and setup support for MCP connections.
Microsoft Foundry supportPython SDKC# SDKJavaScript SDKJava SDKREST APIBasic agent setupStandard agent setup
✔️✔️✔️✔️✔️✔️✔️✔️

​
Prerequisites

Before you begin, make sure you have:
  • An Azure subscription with an active Microsoft Foundry project.
  • Azure role-based access control (RBAC): Contributor or Owner role on the Foundry project.
  • The latest SDK package for your language. The .NET SDK is currently in preview. For installation details, see the quickstart.
  • Azure credentials configured for authentication (such as DefaultAzureCredential).
  • Access to a remote MCP server endpoint (such as GitHub’s MCP server at https://api.githubcopilot.com/mcp).

​
Public and private MCP server endpoints

Agent Service supports both public and private MCP server endpoints:
  • Public endpoints: Connect to any publicly accessible remote MCP server. This option works with both Basic and Standard agent setups.
  • Private endpoints: Connect to MCP servers that aren’t exposed to the public internet. Private MCP requires Standard Agent Setup with private networking and a dedicated MCP subnet within your virtual network.
For private MCP servers, deploy your MCP server on Azure Container Apps with internal-only ingress on a dedicated MCP subnet delegated to Microsoft.App/environments. To get started, use the 19-private-network-agents-tools-setup template, which provisions the required network infrastructure including the MCP subnet. For details about tool support in network-isolated environments, see Agent tools with network isolation.

​
Use Foundry Toolboxes as MCP endpoints

Foundry Toolboxes (preview) let you bundle multiple tools - such as Web Search, Code Interpreter, File Search, Azure AI Search, MCP servers, OpenAPI tools, and Agent-to-Agent connections - into a single MCP-compatible endpoint. Instead of configuring each tool separately on every agent, create a Toolbox in Foundry and point your agent to the Toolbox endpoint by using the standard mcp tool configuration (server_url and server_label). Because the Toolbox endpoint is MCP-compatible, any runtime that can consume an MCP server can also consume a Toolbox. This compatibility includes Foundry Agent Service, Microsoft Agent Framework, LangGraph, GitHub Copilot SDK, and other MCP-enabled clients. You can add, remove, or reconfigure tools in the Toolbox without changing your agent code. For setup steps, see Create and use a Foundry Toolbox.

​
Authentication

Many MCP servers require authentication. In Foundry Agent Service, use a project connection to store authentication details, such as API keys or bearer tokens, instead of hard-coding credentials in your app. To learn about supported authentication options, including key-based, Microsoft Entra identities, and OAuth identity passthrough, see MCP server authentication.
Set project_connection_id to the ID of your project connection.
When you add the Azure DevOps MCP Server (preview) through the Add Tools catalog, you authenticate to Azure DevOps during the organization connection step and store the authentication as a project connection. Use least-privilege access and review scopes when connecting the organization.
When you use a Foundry Toolbox MCP endpoint, the Toolbox centrally manages authentication. The Toolbox handles credential injection, token refresh, and policy enforcement at runtime for all tools in the bundle. Agents authenticate to the Toolbox endpoint itself by using Microsoft Entra credentials, such as DefaultAzureCredential, and individual tool credentials don’t need to be passed by each agent. For Toolbox auth configuration, see Toolbox prerequisites.

​
Considerations for using non-Microsoft services and servers

You’re subject to the terms between you and the service provider when you use connected non-Microsoft services. When you connect to a non-Microsoft service, you pass some of your data, such as prompt content, to the non-Microsoft service, or your application might receive data from the non-Microsoft service. You’re responsible for your use of non-Microsoft services and data, along with any charges associated with that use. Third parties, not Microsoft, create the remote MCP servers that you decide to use with the MCP tool described in this article. Microsoft doesn’t test or verify these servers. Microsoft has no responsibility to you or others in relation to your use of any remote MCP servers. Carefully review and track what MCP servers you add to Foundry Agent Service. Rely on servers hosted by trusted service providers themselves rather than proxies. The MCP tool allows you to pass custom headers, such as authentication keys or schemas, that a remote MCP server might need. Review all data that you share with remote MCP servers and log the data for auditing purposes. Be aware of non-Microsoft practices for retention and location of data.
Foundry Toolboxes are different from third-party MCP servers. Toolboxes are organization-governed resources that you create and manage within your Microsoft Foundry project. However, you’re still responsible for tool selection, data handling, and compliance when curating Toolbox contents.

​
Best practices

For general guidance on tool usage, see Best practices for using tools in Microsoft Foundry Agent Service. When you use MCP servers, follow these practices:
  • Use an allow list of tools by using allowed_tools.
  • Require approval for high-risk operations, especially tools that write data or change resources.
  • Review the requested tool name and arguments before you approve.
  • Log approvals and tool calls for auditing and troubleshooting.
When you add the Azure DevOps MCP Server through the Add Tools catalog, the tool selection configuration maps to the allowed_tools behavior described in this article. Selecting a subset of tools in the catalog UI is equivalent to specifying an allowed_tools list in code.

​
Create an agent in Python with the MCP tool

Use the following code sample to create an agent and call the function. The .NET SDK is currently in preview. See the quickstart for details.

​
How it works

You need to bring a remote MCP server (an existing MCP server endpoint) to Foundry Agent Service. You can bring multiple remote MCP servers by adding them as tools. For each tool, you need to provide a unique server_label value within the same agent and a server_url value that points to the remote MCP server. Be sure to carefully review which MCP servers you add to Foundry Agent Service. In addition to connecting arbitrary remote MCP servers by URL, some MCP servers can be added directly from the Foundry Add Tools catalog. For example, Azure DevOps MCP Server (preview) is available as a catalog entry. Catalog entries simplify connection setup and align with the same approval and auditing mechanisms documented in this article. For more information on using MCP, see:

​
Set up the MCP connection

The following steps outline how to connect to a remote MCP server from Foundry Agent Service:
  1. Find the remote MCP server that you want to connect to, such as the GitHub MCP server. Create or update a Foundry agent with an mcp tool by using the following information:
    1. server_url: The URL of the MCP server, such as https://api.githubcopilot.com/mcp/.
    2. server_label: A unique identifier of this MCP server to the agent, such as github.
    3. allowed_tools: An optional list of tools that this agent can access and use. If you don’t provide this value, the default value includes all of the tools in the MCP server.
    4. require_approval: Optionally determine whether approval is required. The default value is always. Supported values are:
      • always: A developer needs to provide approval for every call. If you don’t provide a value, this one is the default.
      • never: No approval is required.
      • {"never":[<tool_name_1>, <tool_name_2>]}: You provide a list of tools that don’t require approval.
      • {"always":[<tool_name_1>, <tool_name_2>]}: You provide a list of tools that require approval.
  2. project_connection_id: The project connection ID that stores authentication and other connection details for the MCP server.
  3. If the model tries to invoke a tool in your MCP server with approval required, you get a response output item type as mcp_approval_request. In the response output item, you can get more details on which tool in the MCP server is called and arguments to be passed. Review the tool and arguments so that you can make an informed decision for approval.
  4. Submit your approval to the agent by using previous_response_id and setting approve to true.

​
Connect to Azure DevOps MCP Server

Azure DevOps MCP Server (preview) is available as a catalog entry in Foundry. To add it:
  1. In Foundry portal, go to your project.
  2. Select Add Tools > Catalog and search for “Azure DevOps.”
  3. Select Azure DevOps MCP Server (preview) and select Create.
  4. Enter your Azure DevOps organization name and select Connect.
  5. Choose which Azure DevOps tools to expose to your agent. You can select a subset of tools to control exactly what the agent can access.
This catalog-based setup creates the MCP tool for use by agents without requiring code changes. You can validate connectivity and tool behavior in the Foundry chat testing experience before integrating the tool into production code.
Toolbox versioning: Foundry Toolboxes support versioning, so you can iterate on a new version without affecting production agents. Use the consumer endpoint ({project_endpoint}/toolboxes/{name}/mcp?api-version=v1) for production agents - it always serves the promoted default version. Use the version-specific endpoint ({project_endpoint}/toolboxes/{name}/versions/{version}/mcp?api-version=v1) to test before promoting. Keep server_label unique per agent, even when switching Toolbox versions. For details, see Promote a version to default.

​
Known limitations

  • Non-streaming MCP tool call timeout: Non-streaming MCP tool calls have a timeout of 100 seconds. If your MCP server takes longer than 100 seconds to respond, the call fails. To avoid timeouts, ensure that your MCP server responds within this limit. If your use case requires longer processing times, consider optimizing the server-side logic or breaking the operation into smaller steps.
  • Private MCP requires Standard Agent Setup: Private MCP server connectivity is only available with Standard Agent Setup with private networking (BYO VNet). Basic agent setup doesn’t support private MCP endpoints.
  • Private MCP hosting: Azure Container Apps on a dedicated MCP subnet is the tested configuration for private MCP servers. Function Apps or App Services as the private MCP server host might work but aren’t internally validated.

​
Common questions and errors

The following common issues might occur when you use MCP tools with Foundry Agent Service:
  • “Invalid tool schema”: This error usually happens if your MCP server definition includes anyOf or allOf, or if a parameter accepts multiple types of values. Update your MCP server definition and try again.
  • “Unauthorized” or “Forbidden” from the MCP server: Confirm the MCP server supports your authentication method, and verify the credentials stored in your project connection. For GitHub, use least-privilege tokens and rotate them regularly.
  • The model never calls your MCP tool: Confirm your agent instructions encourage tool usage, and verify server_label, server_url, and allowed_tools values. If you set allowed_tools, make sure the tool name matches what the MCP server exposes.
  • The agent never continues after approval: Confirm you send a follow-up request with previous_response_id set to the original response ID, and that you use the approval request item ID as approval_request_id.

​
Host a local MCP server

The Agent Service runtime only accepts a remote MCP server endpoint. If you want to add tools from a local MCP server, you need to self-host it on Azure Container Apps or Azure Functions to get a remote MCP server endpoint. The remote endpoint can be either a public endpoint or a private endpoint within your VNet. For private MCP servers, deploy your Container App with internal-only ingress (--internal-only true) on a dedicated MCP subnet. See Public and private MCP server endpoints for setup details. Consider the following factors when hosting local MCP servers in the cloud:
Local MCP server setupHosting in Azure Container AppsHosting in Azure Functions
TransportHTTP POST/GET endpoints required.HTTP streamable required.
Code changesContainer rebuild required.Azure Functions-specific configuration files required in the root directory.
AuthenticationCustom authentication implementation required.Key-based only. OAuth needs API Management.
LanguageAny language that runs in Linux containers (Python, Node.js, .NET, TypeScript, Go).Python, Node.js, Java, .NET only.
Container requirementsLinux (linux/amd64) only. No privileged containers.Containerized servers aren’t supported.
DependenciesAll dependencies must be in container image.OS-level dependencies (such as Playwright) aren’t supported.
StateStateless only.Stateless only.
UVX/NPXSupported.Not supported. npx start commands not supported.

​
Related content