你当前正在访问 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 的详细信息,请参阅:
- 模型上下文协议网站上的安全最佳做法。
- 在Microsoft安全社区博客中了解和缓解 MCP 实现中的安全风险。
设置
以下步骤概述了如何从 Foundry 代理服务连接到远程 MCP 服务器:
- 查找要连接到的远程 MCP 服务器,例如 GitHub MCP 服务器。 使用
mcp工具创建或更新 Foundry 代理,并提供以下信息:-
server_url:MCP 服务器的 URL,例如https://api.githubcopilot.com/mcp/。 -
server_label:此 MCP 服务器的唯一标识符,例如github。 -
allowed_tools:此代理可以访问和使用的工具的可选列表。 如果未提供此值,则默认值包括 MCP 服务器中的所有工具。 -
require_approval:(可选)确定是否需要审批。 默认值为always。 支持的值为:-
always:开发人员需要为每个呼叫提供审批。 如果未提供值,则此值为默认值。 -
never:无需审批。 -
{"never":[<tool_name_1>, <tool_name_2>]}:提供不需要审批的工具列表。 -
{"always":[<tool_name_1>, <tool_name_2>]}:提供需要审批的工具列表。
-
-
project_connection_id:项目连接的名称
-
- 如果模型尝试在 MCP 服务器中调用需要审批的工具,您将获得一个响应输出项类型为
mcp_approval_request。 在响应输出项中,可以获取有关 MCP 服务器中哪个工具的调用和要传递的参数的更多详细信息。 查看工具和参数,以便你可以做出明智的决策以供审批。 - 将
response_id设置为approve,向具有true的代理提交审批。
常见问题和错误
以下是在 Foundry 代理服务中使用 MCP 工具时可能会遇到的常见问题:
“工具架构无效”:
无效的工具架构通常发生在您的 MCP 服务器定义中具有
anyOf或allOf,或者当某个参数可以接受多种类型的值时。 更新 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 不支持启动命令。 |