你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

连接到模型上下文协议服务器(预览版)

重要

本文中标记了“(预览版)”的项目目前为公共预览版。 此预览版未提供服务级别协议,不建议将其用于生产工作负载。 某些功能可能不受支持或者受限。 有关详细信息,请参阅 Microsoft Azure 预览版补充使用条款

注释

使用 网络安全Microsoft Foundry 时,不能使用在同一虚拟网络中部署的专用 MCP 服务器。 只能使用可公开访问的 MCP 服务器。

将 Foundry 代理连接到 模型上下文协议 (MCP) 服务器,以使用外部工具和数据源扩展代理功能。 通过连接远程 MCP 服务器终结点,您的代理可以访问开发人员和组织托管的工具,这些工具可以被诸如 Foundry 代理服务这样的 MCP 兼容客户端使用。

MCP 是一个开放标准,用于定义应用程序如何向大型语言模型(LLM)提供工具和上下文数据。 它支持将外部工具与模型工作流的一致、可缩放集成。

使用非Microsoft服务和服务器的注意事项

您使用连接的非Microsoft服务受你与服务提供商之间的条款的约束。 连接到非Microsoft服务时,某些数据(如提示内容)将传递到非Microsoft服务,或者应用程序可能会从非Microsoft服务接收数据。 你负责使用非Microsoft服务和数据,以及与使用该服务相关的任何费用。

你决定用于本文所述的 MCP 工具的远程 MCP 服务器由第三方创建,而不是Microsoft。 Microsoft不会测试或验证这些服务器。 Microsoft对你或他人使用任何远程 MCP 服务器不负任何责任。

建议仔细查看和跟踪添加到 Foundry 代理服务的 MCP 服务器。 我们还建议你依赖于受信任的服务提供商本身托管的服务器,而不是代理。

MCP 工具允许你传递远程 MCP 服务器可能需要的自定义标头,例如身份验证密钥或架构。 建议查看与远程 MCP 服务器共享的所有数据,并记录数据以进行审核。 注意用于保留和找到数据的非 Microsoft 做法。

代码示例

使用以下代码示例创建代理并调用函数。 需要最新的预发行版包。 有关详细信息,请参阅 快速入门

import os
from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, MCPTool, Tool
from openai.types.responses.response_input_param import McpApprovalResponse, ResponseInputParam


load_dotenv()

endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):

    # [START tool_declaration]
    tool = MCPTool(
        server_label="api-specs",
        server_url="https://api.githubcopilot.com/mcp",
        require_approval="always",
        project_connection_id=os.environ["MCP_PROJECT_CONNECTION_ID"],
    )
    # [END tool_declaration]

    # Create a prompt agent with MCP tool capabilities
    agent = project_client.agents.create_version(
        agent_name="MyAgent7",
        definition=PromptAgentDefinition(
            model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
            instructions="Use MCP tools as needed",
            tools=[tool],
        ),
    )
    print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

    # Create a conversation to maintain context across multiple interactions
    conversation = openai_client.conversations.create()
    print(f"Created conversation (id: {conversation.id})")

    # Send initial request that will trigger the MCP tool
    response = openai_client.responses.create(
        conversation=conversation.id,
        input="What is my username in Github profile?",
        extra_body={"agent": {"name": agent.name, "type": "agent_reference"}},
    )

    # Process any MCP approval requests that were generated
    input_list: ResponseInputParam = []
    for item in response.output:
        if item.type == "mcp_approval_request":
            if item.server_label == "api-specs" and item.id:
                # Automatically approve the MCP request to allow the agent to proceed
                # In production, you might want to implement more sophisticated approval logic
                input_list.append(
                    McpApprovalResponse(
                        type="mcp_approval_response",
                        approve=True,
                        approval_request_id=item.id,
                    )
                )

    print("Final input:")
    print(input_list)

    # Send the approval response back to continue the agent's work
    # This allows the MCP tool to access the GitHub repository and complete the original request
    response = openai_client.responses.create(
        input=input_list,
        previous_response_id=response.id,
        extra_body={"agent": {"name": agent.name, "type": "agent_reference"}},
    )

    print(f"Response: {response.output_text}")

    # Clean up resources by deleting the agent version
    # This prevents accumulation of unused agent versions in your project
    project_client.agents.delete_version(agent_name=agent.name, agent_version=agent.version)
    print("Agent deleted")

有关 C# 用法的示例,请参阅 GitHub 上 Azure SDK for .NET 存储库中的 Azure.AI.Projects.OpenAI 示例:使用 MCP 工具和代理,以及 使用 MCP 工具与项目连接的代理

工作原理

需要将远程 MCP 服务器(现有的 MCP 服务器终结点)引入 Foundry 代理服务。 可以通过将它们添加为工具来引入多个远程 MCP 服务器。 对于每个工具,需要在同一代理中提供一个唯一的 server_label 值,并且提供一个指向远程 MCP 服务器的 server_url 值。 请务必仔细查看添加到 Foundry 代理服务的 MCP 服务器。

有关使用 MCP 的详细信息,请参阅:

设置

以下步骤概述了如何从 Foundry 代理服务连接到远程 MCP 服务器:

  1. 查找要连接到的远程 MCP 服务器,例如 GitHub MCP 服务器。 使用 mcp 工具创建或更新 Foundry 代理,并提供以下信息:
    1. server_url:MCP 服务器的 URL,例如 https://api.githubcopilot.com/mcp/
    2. server_label:此 MCP 服务器的唯一标识符,例如 github
    3. allowed_tools:此代理可以访问和使用的工具的可选列表。 如果未提供此值,则默认值包括 MCP 服务器中的所有工具。
    4. require_approval:(可选)确定是否需要审批。 默认值为 always。 支持的值为:
      • always:开发人员需要为每个呼叫提供审批。 如果未提供值,则此值为默认值。
      • never:无需审批。
      • {"never":[<tool_name_1>, <tool_name_2>]}:提供不需要审批的工具列表。
      • {"always":[<tool_name_1>, <tool_name_2>]}:提供需要审批的工具列表。
    5. project_connection_id:项目连接的名称
  2. 如果模型尝试在 MCP 服务器中调用需要审批的工具,您将获得一个响应输出项类型为 mcp_approval_request。 在响应输出项中,可以获取有关 MCP 服务器中哪个工具的调用和要传递的参数的更多详细信息。 查看工具和参数,以便你可以做出明智的决策以供审批。
  3. response_id 设置为 approve,向具有 true 的代理提交审批。

常见问题和错误

以下是在 Foundry 代理服务中使用 MCP 工具时可能会遇到的常见问题:

  • “工具架构无效”:

    无效的工具架构通常发生在您的 MCP 服务器定义中具有 anyOfallOf,或者当某个参数可以接受多种类型的值时。 更新 MCP 服务器定义,然后重试。

托管本地 MCP 服务器

智能体服务运行时仅接受远程 MCP 服务器终结点。 如果要从本地 MCP 服务器添加工具,则需要在 Azure 容器应用Azure Functions 上自行托管该工具,以获取远程 MCP 服务器终结点。 在云中托管本地 MCP 服务器时,请考虑以下因素:

本地 MCP 服务器设置 在 Azure 容器应用中托管 在 Azure Functions 中托管
Transport 需要 HTTP POST/GET 终结点。 需要 HTTP 流式传输。
代码更改 需要容器重建。 根目录中所需的特定于 Azure Functions 的配置文件。
身份验证 需要自定义身份验证实现。 仅基于密钥。 OAuth 需要 API 管理。
语言 在 Linux 容器中运行的任何语言(Python、Node.js、.NET、TypeScript、Go)。 Python、Node.js、Java、.NET。
容器要求 仅限 Linux(linux/amd64)。 没有特权容器。 不支持容器化服务器。
依赖 所有依赖项都必须位于容器映像中。 不支持 OS 级依赖项(如 Playwright)。
仅限无状态。 仅限无状态。
UVX/NPX 支持. 不支持。 npx 不支持启动命令。