partition security content

gitName · gitName · commit 0cbef6073795 · 2025-07-30T15:58:34.000-07:00
diff --git a/articles/api-management/TOC.yml b/articles/api-management/TOC.yml
@@ -260,6 +260,8 @@
       href: export-rest-mcp-server.md
     - name: Expose existing MCP server
       href: expose-existing-mcp-server.md
+    - name: Secure access to MCP servers
+      href: secure-mcp-servers.md
 - name: Manage APIs with policies
   items:
   - name: API Management policies overview
diff --git a/articles/api-management/export-rest-mcp-server.md b/articles/api-management/export-rest-mcp-server.md
@@ -44,6 +44,8 @@ The following limitations currently apply to this preview:
     > [!NOTE]
     > Other API types in API Management that aren't HTTP-compatible can't be exposed as MCP servers.
 
++ If you’ve enabled diagnostic logging via Application Insights or Azure Monitor at the global scope (All APIs) for your API Management service instance, ensure that the **Number of payload bytes to log** setting for Frontend Response is set to 0. This prevents unintended logging of response bodies across all APIs and helps ensure proper functioning of MCP servers. To log payloads selectively for specific APIs, configure the setting individually at the API scope, allowing targeted control over response logging.
+
 + To test the MCP server, you can use Visual Studio Code with access to [GitHub Copilot](https://code.visualstudio.com/docs/copilot/setup).
 
 
diff --git a/articles/api-management/expose-existing-mcp-server.md b/articles/api-management/expose-existing-mcp-server.md
@@ -56,6 +56,8 @@ The following limitations currently apply to this preview:
 
 + Appropriate credentials to the MCP server (such as OAuth 2.0 client credentials or API keys, depending on the server) for secure access.
 
++ If you’ve enabled diagnostic logging via Application Insights or Azure Monitor at the global scope (All APIs) for your API Management service instance, ensure that the **Number of payload bytes to log** setting for Frontend Response is set to 0. This prevents unintended logging of response bodies across all APIs and helps ensure proper functioning of MCP servers. To log payloads selectively for specific APIs, configure the setting individually at the API scope, allowing targeted control over response logging.
+
 + To test the MCP server, you can use Visual Studio Code with access to [GitHub Copilot](https://code.visualstudio.com/docs/copilot/setup).
 
 ## Expose an existing MCP server
diff --git a/articles/api-management/mcp-server-overview.md b/articles/api-management/mcp-server-overview.md
@@ -85,45 +85,7 @@ Configure policies such as the following::
 
 ## Secure access to the MCP server
 
-You can secure either or both inbound access to the MCP server (from an MCP client to API Management) and outbound access (from API Management to the MCP server backend).
-
-### Secure inbound access
-
-One option to secure inbound access is to configure a policy to validate a JSON web token (JWT) generated using an identity provider in the incoming requests. This ensures that only authorized clients can access the MCP server. Use the generic [validate-jwt](validate-jwt-policy.md) policy, or the [validate-azure-ad-token](validate-azure-ad-token-policy.md) policy when using Microsoft Entra ID, to validate the JWT token in the incoming requests. 
-
-The following is a basic example of validating a Microsoft Entra ID token presented in an `Authorization` header in the incoming request:
-
-```xml
-<validate-azure-ad-token header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">     
-    <client-application-ids>
-        <application-id>your-client-id</application-id>
-    </client-application-ids> 
-</validate-azure-ad-token>
-```
-
-For more inbound authorization options and samples, including using OAuth authorization, see:
-
-* [MCP server authorization with Protected Resource Metadata (PRM) sample](https://github.com/blackchoey/remote-mcp-apim-oauth-prm)
-
-* [Secure Remote MCP Servers using Azure API Management (Experimental)](https://github.com/Azure-Samples/remote-mcp-apim-functions-python)
-
-* [MCP client authorization lab](https://github.com/Azure-Samples/AI-Gateway/tree/main/labs/mcp-client-authorization)
-
-> [!CAUTION]
-> When you use an MCP server in API Management, incoming headers like **Authorization** aren't automatically passed to your backend API. If your backend needs a token, you can add it as an input parameter in your API definition. Alternatively, use policies like `get-authorization-context` and `set-header` to generate and attach the token, as noted in the following section.
-
-
-### Secure outbound access
-
-You can use API Management's [credential manager](credentials-overview.md) to securely inject secrets or tokens for calls to a backend API. At a high level, the process is as follows:
-
-1. Register an application in a supported identity provider.
-1. Create a credential provider resource in API Management to manage the credentials from the identity provider.
-1. Configure a connection to the provider in API Management.
-1. Configure `get-authorization-context` and `set-header` policies to fetch the token credentials and present them in an **Authorization** header of the API requests.
-
-For a step-by-step guide to call an example backend API using credentials generated in credential manager, see [Configure credential manager - GitHub](credentials-how-to-github.md).
- 
+You can secure either or both inbound access to the MCP server (from an MCP client to API Management) and outbound access (from API Management to the MCP server backend). For information and examples, see [Secure access to MCP servers](secure-mcp-servers.md).
 
 ## Monitoring
 
@@ -147,16 +109,14 @@ Use [Azure API Center](../api-center/register-discover-mcp-server.md) to registe
 
 ## Availability
 
-<!-- availability in workspaces?-->
-
-
 MCP servers in API Management are available in the following service tiers:
 
 * **Classic tiers**: Basic, Standard, Premium
 * **v2 tiers**: Basic v2, Standard v2, Premium v2
 
 > [!NOTE]
-> In the classic tiers, you must join the [AI Gateway Early update group](configure-service-update-settings.md) to access MCP server features, and access the portal at a feature-specific URL.
+> * In the classic tiers, you must join the [AI Gateway Early update group](configure-service-update-settings.md) to access MCP server features, and access the portal at a feature-specific URL.
+> * MCP servers aren't currently supported in [workspaces](workspaces-overview.md).
 
 ## Related content
 
@@ -168,4 +128,6 @@ MCP servers in API Management are available in the following service tiers:
 
 * [Expose REST API in API Management as an MCP server](export-rest-mcp-server.md)
 
-* [Expose and govern existing MCP server](expose-existing-mcp-server.md)
+* [Expose and govern existing MCP server](expose-existing-mcp-server.md)
+
+* [Secure access to MCP servers](secure-mcp-servers.md)
diff --git a/articles/api-management/secure-mcp-servers.md b/articles/api-management/secure-mcp-servers.md
@@ -0,0 +1,68 @@
+---
+title: Secure access to MCP servers in Azure API Management
+description: Learn how secure access to MCP servers managed in Azure API Management.
+author: dlepow
+ms.service: azure-api-management
+ms.topic: concept-article
+ms.date: 07/30/2025
+ms.author: danlep
+ms.collection: ce-skilling-ai-copilot
+ms.custom:
+---
+
+# Secure access to MCP servers in API Management
+
+[!INCLUDE [api-management-availability-premium-standard-basic-premiumv2-standardv2-basicv2](../../includes/api-management-availability-premium-standard-basic-premiumv2-standardv2-basicv2.md)]
+
+
+With  [MCP server support in API Management](mcp-server-overview.md), you can expose and govern access to MCP servers and their tools. This article describes how to secure access to MCP servers managed in API Management, including both MCP servers exposed from managed REST APIs and existing MCP servers hosted outside of API Management.
+
+You can secure either or both inbound access to the MCP server (from an MCP client to API Management) and outbound access (from API Management to the MCP server backend).
+
+### Secure inbound access
+
+One option to secure inbound access is to configure a policy to validate a JSON web token (JWT) generated using an identity provider in the incoming requests. This ensures that only authorized clients can access the MCP server. Use the generic [validate-jwt](validate-jwt-policy.md) policy, or the [validate-azure-ad-token](validate-azure-ad-token-policy.md) policy when using Microsoft Entra ID, to validate the JWT in the incoming requests. 
+
+The following is a basic example of validating a Microsoft Entra ID token presented in an `Authorization` header in the incoming request:
+
+```xml
+<validate-azure-ad-token header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">     
+    <client-application-ids>
+        <application-id>your-client-id</application-id>
+    </client-application-ids> 
+</validate-azure-ad-token>
+```
+
+For more inbound authorization options and samples, including using OAuth authorization, see:
+
+* [MCP server authorization with Protected Resource Metadata (PRM) sample](https://github.com/blackchoey/remote-mcp-apim-oauth-prm)
+
+* [Secure Remote MCP Servers using Azure API Management (Experimental)](https://github.com/Azure-Samples/remote-mcp-apim-functions-python)
+
+* [MCP client authorization lab](https://github.com/Azure-Samples/AI-Gateway/tree/main/labs/mcp-client-authorization)
+
+> [!CAUTION]
+> When you use an MCP server in API Management, incoming headers like **Authorization** aren't automatically passed to your backend API. If your backend needs a token, you can add it as an input parameter in your API definition. Alternatively, use policies like `get-authorization-context` and `set-header` to generate and attach the token, as noted in the following section.
+
+
+### Secure outbound access
+
+You can use API Management's [credential manager](credentials-overview.md) to securely inject secrets or tokens for calls to a backend API. For example, use the credential manager to obtain and present an access token from an identity provider to access the API called by an MCP server tool.
+
+At a high level, the process is as follows:
+
+1. Register an application in a supported identity provider.
+1. Create a credential provider resource in API Management to manage the credentials from the identity provider.
+1. Configure a connection to the provider in API Management.
+1. Configure `get-authorization-context` and `set-header` policies to fetch the token credentials and present them in an **Authorization** header of the API requests.
+
+For a step-by-step guide to call an example backend API using credentials generated in credential manager, see [Configure credential manager - GitHub](credentials-how-to-github.md).
+
+## Related content
+
+
+* [Register and discover remote MCP servers in Azure API Center](../api-center/register-discover-mcp-server.md)
+
+* [Expose REST API in API Management as an MCP server](export-rest-mcp-server.md)
+
+* [Expose and govern existing MCP server](expose-existing-mcp-server.md)
diff --git a/includes/api-management-configure-test-mcp-server.md b/includes/api-management-configure-test-mcp-server.md
@@ -15,6 +15,9 @@ Learn more about configuring policies:
 * [Transform and protect your API](../articles/api-management/transform-api.md)
 * [Set and edit policies](../articles/api-management/set-edit-policies.md)
 
+> [!IMPORTANT]
+> Do not access the response body using `context.Response.Body` within MCP server policies. Doing so triggers response buffering, which interferes with the streaming behavior required by MCP servers and may cause them to malfunction.
+
 To configure policies for the MCP server:
 
 1. In the [Azure portal](https://portal.azure.com), navigate to your API Management instance.
@@ -86,6 +89,7 @@ After adding an MCP server in Visual Studio Code, you can use tools in agent mod
 | `401 Unauthorized` error from backend           | Authorization header not forwarded        | Use `set-header` policy to manually attach token         |
 | API call works in API Management but fails in agent | Incorrect base URL or missing token       | Double-check security policies and endpoint            |
 | Not able to create MCP server           | MCP server capability is not available in Consumption or Developer tier, and must be enabled using [update group](../articles/api-management/configure-service-update-settings.md) in classic Basic, Standard, and Premium tiers  | Use a supported classic or v2 tier - see [Prerequisites](#prerequisites) |
+|  | | |
 
 ## Related content
 
