Merge pull request #5947 from ShawnJackson/azure-ai-foundry-agent-service-mcp-documentation

[AQ] edit pass: Azure AI Foundry Agent Service MCP documentation

Author: ktoliver

articles/ai-foundry/agents/how-to/tools/model-context-protocol-samples.md

@@ -1,7 +1,7 @@
 ---
-title: 'MCP tool code samples'
+title: Code Samples for the Model Context Protocol Tool (Preview)
 titleSuffix: Azure AI Foundry
-description: Find code samples to connect Foundry Agent service with MCP.
+description: Find code samples to connect Azure AI Foundry Agent Service with MCP servers.
 services: cognitive-services
 manager: nitinme
 ms.service: azure-ai-agent-service
@@ -13,13 +13,14 @@ zone_pivot_groups: selection-mcp-code
 ms.custom: azure-ai-agents-code
 ---
 
-# How to use the Model Context Protocol (MCP) tool
+# Code samples for the Model Context Protocol tool (preview)
 
-Use this article to find step-by-step instructions and code samples for connecting Foundry Agent service with MCP.
+Use this article to find code samples for connecting Azure AI Foundry Agent Service with Model Context Protocol (MCP) servers.
 
 :::zone pivot="python"
 
-## Initialization
+## Initialize the client
+
 The code begins by setting up the necessary imports, getting the relevant MCP server configuration, and initializing the AI Project client:
 
 ```python
@@ -29,7 +30,7 @@ from azure.ai.projects import AIProjectClient
 from azure.identity import DefaultAzureCredential
 from azure.ai.agents.models import McpTool, RequiredMcpToolCall, SubmitToolApprovalAction, ToolApproval
 
-# Get MCP server configuration from environment variables
+# Get the MCP server configuration from environment variables
 mcp_server_url = os.environ.get("MCP_SERVER_URL", "https://gitmcp.io/Azure/azure-rest-api-specs")
 mcp_server_label = os.environ.get("MCP_SERVER_LABEL", "github")
 
@@ -39,8 +40,9 @@ project_client = AIProjectClient(
 )
 ```
 
-## Tool setup
-To add the MCP server to the agent, use the following example, which takes the MCP server label and URL from the last step. You can also add or remove allowed tools dynamically through the `allow_tool` parameter. 
+## Set up the tool
+
+To add the MCP server to the agent, use the following example, which takes the MCP server label and URL from the previous step. You can also add or remove allowed tools dynamically through the `allow_tool` parameter.
 
 ```python
 mcp_tool = McpTool(
@@ -55,17 +57,18 @@ mcp_tool.allow_tool(search_api_code)
 print(f"Allowed tools: {mcp_tool.allowed_tools}")
 ```
 
-## Agent creation
-An agent is created using the `project_client.agents.create_agent` method.
+## Create an agent
+
+You create an agent by using the `project_client.agents.create_agent` method:
 
 ```python
 # Create a new agent.
-# NOTE: To reuse existing agent, fetch it with get_agent(agent_id)
+# NOTE: To reuse an existing agent, fetch it with get_agent(agent_id)
 with project_client:
     agents_client = project_client.agents
 
     # Create a new agent.
-    # NOTE: To reuse existing agent, fetch it with get_agent(agent_id)
+    # NOTE: To reuse an existing agent, fetch it with get_agent(agent_id)
     agent = agents_client.create_agent(
         model=os.environ["MODEL_DEPLOYMENT_NAME"],
         name="my-mcp-agent",
@@ -74,15 +77,16 @@ with project_client:
     )
 ```
 
-## Thread management
-Create the thread and add the initial user message.
+## Create a thread
+
+Create the thread and add the initial user message:
 
 ```python
-# Create thread for communication
+# Create a thread for communication
 thread = agents_client.threads.create()
 print(f"Created thread, ID: {thread.id}")
 
-# Create message to thread
+# Create a message for the thread
 message = agents_client.messages.create(
     thread_id=thread.id,
     role="user",
@@ -91,20 +95,20 @@ message = agents_client.messages.create(
 print(f"Created message, ID: {message.id}")
 ```
 
-## Handle tool approvals and create a run
+## Handle tool approvals
 
-Set the MCP server update headers and optionally disable tool approval requirements.
+Set the MCP server update headers and optionally disable tool approval requirements:
 
 ```python
 mcp_tool.update_headers("SuperSecret", "123456")
-# mcp_tool.set_approval_mode("never")  # Uncomment to disable approval requirement
+# mcp_tool.set_approval_mode("never")  # Uncomment to disable approval requirements
 run = agents_client.runs.create(thread_id=thread.id, agent_id=agent.id, tool_resources=mcp_tool.resources)
 print(f"Created run, ID: {run.id}")
 ```
 
-
 ## Create a run and check the output
-Create the run, check the output, and examine what tools were called during the run.
+
+Create the run, check the output, and examine what tools were called during the run:
 
 ```python
     # Create and automatically process the run, handling tool calls internally
@@ -133,9 +137,9 @@ Create the run, check the output, and examine what tools were called during the
         print()
 ```
 
+## Perform cleanup
 
-## Cleanup
-After the interaction is complete, the script performs cleanup by deleting the created agent resource using `agents_client.delete_agent()` to avoid leaving unused resources. It also fetches and prints the entire message history from the thread using `agents_client.list_messages()` for review or logging.
+After the interaction is complete, the script performs cleanup by deleting the created agent resource via `agents_client.delete_agent()` to avoid leaving unused resources. It also fetches and prints the entire message history from the thread by using `agents_client.list_messages()` for review or logging.
 
 ```python
         # Delete the agent resource to clean up
@@ -152,24 +156,24 @@ After the interaction is complete, the script performs cleanup by deleting the c
 
 :::zone pivot="rest"
 
-Follow the [REST API Quickstart](../../quickstart.md?pivots=rest-api#api-call-information) to set the right values for the environment variables `AGENT_TOKEN`, `AZURE_AI_FOUNDRY_PROJECT_ENDPOINT`, and `API_VERSION`.
+Follow the [REST API quickstart](../../quickstart.md?pivots=rest-api#api-call-information) to set the right values for the environment variables `AGENT_TOKEN`, `AZURE_AI_FOUNDRY_PROJECT_ENDPOINT`, and `API_VERSION`.
 
+## Create an agent with the MCP tool enabled
 
-## Create an Agent with the MCP tool enabled
+To make the MCP tool available to your agent, initialize a tool with the server endpoint, server label, and more:
 
-To make the MCP tool available to your agent, initialize a tool with the server endpoint, server label and more
 ```bash
 curl --request POST \
   --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/assistants?api-version=$API_VERSION \
   -H "Authorization: Bearer $AGENT_TOKEN" \
   -H "Content-Type: application/json" \
   -d "{
-	  "instructions": "You are a customer support chatbot. Use the tools provided and your knowledge base to best respond to customer queries.",
-  	"tools": [
+    "instructions": "You are a customer support chatbot. Use the tools provided and your knowledge base to best respond to customer queries.",
+    "tools": [
           {
               "type": "mcp",
               "server_label": "<unique name for your MCP server>",
-              "server_url": "<your MCP server url>",
+              "server_url": "<your MCP server URL>",
               "allowed_tools": ["<tool_name>"], # optional
           }
       ],
@@ -203,26 +207,27 @@ curl --request POST \
 
 ## Create a run and check the output
 
-Create a run to pass headers for the tool and observe that the model uses the Grounding with Bing Search tool to provide a response to the user's question. 
-`require_approval` parameter is optional. If not provided, `always` is the default value, meaning each time developer needs to approve before calling. Supported values:
+Create a run to pass headers for the tool. Observe that the model uses the Grounding with Bing Search tool to provide a response to the user's question.
+
+The `require_approval` parameter is optional. Supported values are:
 
-- `always` by default
-- `never` meaning no approval is required
-- `{"never":[<tool_name_1>, <tool_name_2>]}` you can also provide a list of tools without required approval
-- `{"always":[<tool_name_1>, <tool_name_2>]}` you can provide a list of tools with required approval
+- `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.
 
 ```bash
 curl --request POST \
   --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs?api-version=$API_VERSION \
   -H "Authorization: Bearer $AGENT_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
-	    "assistant_id": "<agent_id>",
-    	"tool_resources": {
+      "assistant_id": "<agent_id>",
+      "tool_resources": {
           "mcp": [
             {
                 "server_label": "<the same unique name you provided during agent creation>",
-		"require_approval": "always" #always by default
+    "require_approval": "always" #always by default
                 "headers": {
                     "Authorization": "Bearer <token>",
                 }
@@ -232,6 +237,7 @@ curl --request POST \
       },
     }'
 ```
+
 ## Retrieve the status of the run
 
 ```bash
@@ -240,7 +246,8 @@ curl --request GET \
   -H "Authorization: Bearer $AGENT_TOKEN"
 ```
 
-If the model is trying to invoke a tool in your MCP server with approval required, you get a run with `require_action` status.
+If the model tries to invoke a tool in your MCP server with approval required, you get a run with `requires_action` status:
+
 ```bash
 {
   "id": "run_123",
@@ -274,17 +281,20 @@ If the model is trying to invoke a tool in your MCP server with approval require
  ...
 }
 ```
-Make sure you carefully reviewed the tool and argument(s) to be passed and make an informed decision for approval.
+
+Carefully review the tool and arguments to be passed so that you can make an informed decision for approval.
 
 ## Submit your approval
-If you decide to approve, you need to set the `approve` parameter to be `true` with the `id` for the preceding tool calls.
+
+If you decide to approve, set the `approve` parameter to `true` with the `id` value for the preceding tool calls:
+
 ```bash
 curl --request POST \
   --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs/run_abc123/submit_tool_outputs?api-version=$API_VERSION \
   -H "Authorization: Bearer $AGENT_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
-	"tool_approvals": [
+  "tool_approvals": [
         {
             "tool_call_id": "call_abc123",
             "approve": true,
@@ -295,7 +305,6 @@ curl --request POST \
 }
 ```
 
-
 ## Retrieve the agent response
 
 ```bash
@@ -305,4 +314,3 @@ curl --request GET \
 ```
 
 :::zone-end
-