wip

gitName · gitName · commit 008ff9c7a2b5 · 2025-07-30T18:20:49.000-07:00
diff --git a/articles/api-management/mcp-server-overview.md b/articles/api-management/mcp-server-overview.md
@@ -14,10 +14,15 @@ ms.custom:
 
 [!INCLUDE [api-management-availability-premium-standard-basic-premiumv2-standardv2-basicv2](../../includes/api-management-availability-premium-standard-basic-premiumv2-standardv2-basicv2.md)]
 
-This article introduces features in Azure API Management that you can use to manage Model Context Protocol (MCP) servers. MCP servers allow AI agents to access external data sources, such as databases or APIs, through a standardized protocol. 
+This article introduces features in Azure API Management that you can use to manage Model Context Protocol (MCP) servers. MCP servers allow large language models (LLMs) and AI agents to access external data sources, such as databases or APIs, through a standardized protocol. 
 
-Use API Management to securely expose and govern API operations as tools for large language models (LLMs) and AI agents like GitHub Copilot, ChatGPT, Claude, and more. API Management provides centralized control over MCP server authentication, authorization, and monitoring. It simplifies the management of MCP servers while helping to mitigate common security risks and ensuring scalability.
+With the proliferation of AI agents and large language models (LLMs), management of MCP servers is becoming increasingly important:
 
+* Agents need secure, governed access to tools and resources
+* Developers want to reuse existing APIs as agent tools
+* Enterprises need observability, control, and scaling
+
+Use API Management to securely expose and govern API operations as tools for LLMs and AI agents like GitHub Copilot, ChatGPT, Claude, and more. API Management provides centralized control over MCP server authentication, authorization, and monitoring. It simplifies the management of MCP servers while helping to mitigate common security risks and ensuring observability, control, and scalability.
 
 ## MCP concepts and architecture
 
@@ -85,7 +90,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). For information and examples, see [Secure access to MCP servers](secure-mcp-servers.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 more information and examples, see [Secure access to MCP servers](secure-mcp-servers.md).
 
 ## Monitoring
 
@@ -103,9 +108,11 @@ For more information, see [Monitor API Management](monitor-api-management.md).
 
 ## Discover MCP servers
 
-Use [Azure API Center](../api-center/register-discover-mcp-server.md) to register and discover MCP servers in your organization. Azure API Center provides a centralized location for managing MCP servers, including those exposed in API Management and those hosted outside of API Management.
+Use [Azure API Center](../api-center/register-discover-mcp-server.md) to register and discover MCP servers in your organization. 
 
+* Azure API Center provides a centralized location for managing MCP servers, including those exposed in API Management and those hosted outside of API Management. 
 
+* Deploy the [API Center portal](../api-center/set-up-api-center-portal.md) to enable your users to discover and interact with MCP servers through a private, enterprise-ready MCP server registry.
 
 ## Availability
 
@@ -115,7 +122,7 @@ MCP servers in API Management are available in the following service tiers:
 * **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.
 > * MCP servers aren't currently supported in [workspaces](workspaces-overview.md).
 
 ## Related content
@@ -130,4 +137,6 @@ MCP servers in API Management are available in the following service tiers:
 
 * [Expose and govern existing MCP server](expose-existing-mcp-server.md)
 
-* [Secure access to MCP servers](secure-mcp-servers.md)
+* [Secure access to MCP servers](secure-mcp-servers.md)
+
+* Visit [https://mcp.azure.com](https://mcp.azure.com) for a live example of an MCP server registry created using Azure API Center.
diff --git a/articles/api-management/secure-mcp-servers.md b/articles/api-management/secure-mcp-servers.md
@@ -19,14 +19,40 @@ With  [MCP server support in API Management](mcp-server-overview.md), you can ex
 
 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
+## 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. 
+### Key-based authentication
 
-The following is a basic example of validating a Microsoft Entra ID token presented in an `Authorization` header in the incoming request:
+If the backend API is protected with an API Management subscription key passed in a `Ocp-Apim-Subscription-Key` header, MCP clients can present the key in the incoming requests, and the MCP server can validate the key. For example, in Visual Studio Code, you can add a `headers` section to the MCP server configuration to require the subscription key in the request headers:
+
+```json
+{
+  "name": "My MCP Server",
+  "type": "remote",
+  "url": "https://my-api-management-instance.azure-api.net/my-mcp-server",    
+  "transport": "streamable-http",
+  "headers": {
+    "Ocp-Apim-Subscription-Key": "<subscription-key>"
+  }
+}
+
+```
+
+Visual Studio Code provides ways to store the subscription key in the workspace or user settings, or to pass the key through user input, so you don't have to hard-code it in the MCP server configuration.
+
+> [!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.
+
+### Token-based authentication
+
+You can generate an access token (JWT) using your identity provider, and pass the token in a request to the MCP server in an `Authorization` header. Then, API Management can use a policy to validate the JWT in the incoming request. This ensures that only authorized clients can access the MCP server. 
+
+API Management provides 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. 
+
+For example, you can use the following policy to validate a Microsoft Entra ID token presented in an 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.">     
+<validate-azure-ad-token tenant-id="your-tenant-id" 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> 
@@ -41,13 +67,10 @@ For more inbound authorization options and samples, including using OAuth author
 
 * [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
+## 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.
+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 OAuth 2.0 access token from an identity provider to access the backend API called by an MCP server tool.
 
 At a high level, the process is as follows:
 
@@ -56,6 +79,22 @@ At a high level, the process is as follows:
 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 example, the following policy retrieves an access token from the credential manager and sets it in the `Authorization` header of the request to the backend API:
+    
+    ```xml
+    <!-- Add to inbound policy. -->
+    <get-authorization-context
+        provider-id="your-credential-provider-id    " 
+        authorization-id="auth-01" 
+        context-variable-name="auth-context" 
+        identity-type="managed" 
+        ignore-error="false" />
+    <!-- Attach the token to the backend call -->
+    <set-header name="Authorization" exists-action="override">
+        <value>@("Bearer " + ((Authorization)context.Variables.GetValueOrDefault("auth-context"))?.AccessToken)</value>
+    </set-header>
+    ```
+
 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
