Not
Bu sayfaya erişim yetkilendirme gerektiriyor. Oturum açmayı veya dizinleri değiştirmeyi deneyebilirsiniz.
Bu sayfaya erişim yetkilendirme gerektiriyor. Dizinleri değiştirmeyi deneyebilirsiniz.
MCP aracını kullanarak Foundry aracılarınızı Model Bağlam Protokolü (MCP) sunucularına bağlayın. Bu bağlantı, aracı özelliklerini dış araçlar ve veri kaynaklarıyla genişletir. Aracınızın Foundry modeli, uzak MCP sunucu uç noktalarına bağlanarak, Foundry Agent Service gibi MCP uyumlu istemcilerin kullanabileceği geliştiriciler ve kuruluşlar tarafından barındırılan araçlara erişebilir.
MCP, uygulamaların büyük dil modellerine (LLM) nasıl araç ve bağlamsal veri sağladığını tanımlayan açık bir standarttır. Dış araçların model iş akışlarıyla tutarlı ve ölçeklenebilir bir şekilde tümleştirilmesini sağlar.
Bu makalede şunların nasıl yapılacağını öğreneceksiniz:
- Uzak bir MCP sunucusunu araç olarak ekleyin.
- Proje bağlantısı kullanarak bir MCP sunucusunda kimlik doğrulaması.
- MCP araç çağrılarını gözden geçirin ve onaylayın.
- Yaygın MCP tümleştirme sorunlarını giderin.
MCP tümleştirmenin nasıl çalıştığı hakkında kavramsal ayrıntılar için bkz. Nasıl çalışır?
Kullanım desteği
Aşağıdaki tabloda, MCP bağlantıları için SDK ve kurulum desteği gösterilmektedir.
| Microsoft Foundry desteği | Python SDK | C# SDK'sı | JavaScript SDK'sı | Java SDK | REST API | Temel aracı kurulumu | Standart ajan kurulumu |
|---|---|---|---|---|---|---|---|
| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
Önkoşullar
Başlamadan önce şunları yaptığınızdan emin olun:
- Etkin Microsoft Dökümhane projesine sahip bir Azure aboneliği.
- Azure rol tabanlı erişim denetimi (RBAC): Dökümhane projesinde katkıda bulunan veya sahip rolü.
- Diliniz için en son SDK paketi. .NET SDK şu anda önizleme aşamasındadır. Yükleme ayrıntıları için hızlı başlangıç bölümüne bakın.
- Azure kimlik doğrulaması için yapılandırılmış kimlik bilgileri (örneğin
DefaultAzureCredential) gibi. - Uzak bir MCP sunucu uç noktasına erişim (GitHub'nin
https://api.githubcopilot.com/mcp'daki MCP sunucusu gibi).
Genel ve özel MCP sunucu uç noktaları
Aracı Hizmeti hem genel hem de özel MCP sunucu uç noktalarını destekler:
- Genel uç noktalar: Genel olarak erişilebilen herhangi bir uzak MCP sunucusuna bağlanın. Bu seçenek hem Temel hem de Standart aracı kurulumlarıyla çalışır.
- Özel uç noktalar: Genel İnternet'e açık olmayan MCP sunucularına bağlanın. Özel MCP, özel ağ ile Standart Aracı Kurulumu ve sanal ağınızda ayrılmış bir MCP alt ağı gerektirir.
Özel MCP sunucuları için, Microsoft.App/environments'a atanan ayrılmış bir MCP alt ağına sadece dahili erişimle Azure Container Apps üzerinde MCP sunucunuzu dağıtın. Başlamak için MCP alt ağı dahil gerekli ağ altyapısını sağlayan 19-hybrid-private-resources-agent-setup şablonunu kullanın.
Ağdan yalıtılmış ortamlardaki araç desteği hakkında ayrıntılı bilgi için bkz. Ağ yalıtımına sahip aracı araçları.
Foundry Araç Kutularını MCP uç noktaları olarak kullanma
Döküm Aracı Kutuları (önizleme), Web Araması, Kod Yorumlayıcı, Dosya Arama, Azure Yapay Zeka Arama, MCP sunucuları, OpenAPI araçları ve Aracıdan Aracıya bağlantılar gibi birden çok aracı MCP uyumlu tek bir uç noktada paketlemenize olanak sağlar. Foundry'de bir Araç Kutusu oluşturun ve her bir aracı ayrı ayrı yapılandırmak yerine, araçlarınızı standart mcp araç yapılandırması aracılığıyla (server_url ve server_label) Araç Kutusu uç noktasına yönlendirin.
Toolbox uç noktası MCP uyumlu olduğundan, bir MCP sunucusu kullanabilen tüm çalışma zamanları Toolbox'u da kullanabilir. Bu uyumluluk Foundry Agent Service, Microsoft Agent Framework, LangGraph, GitHub Copilot SDK ve diğer MCP özellikli istemcileri içerir. Aracı kodunuzu değiştirmeden Araç Kutusu'nda araçları ekleyebilir, kaldırabilir veya yeniden yapılandırabilirsiniz.
Kurulum adımları için Döküm Aracı Kutusu oluşturma ve kullanma bölümüne bakın.
Kimlik doğrulama
Birçok MCP sunucusu kimlik doğrulaması gerektirir.
Foundry Aracısı Hizmeti'nde, uygulamanızda kimlik bilgilerini sabit kodlamak yerine API anahtarları veya taşıyıcı belirteçleri gibi kimlik doğrulama ayrıntılarını depolamak için bir proje bağlantısı kullanın.
Anahtar tabanlı, Microsoft Entra kimlikleri ve OAuth kimlik geçişi de dahil olmak üzere desteklenen kimlik doğrulama seçenekleri hakkında bilgi edinmek için bkz. MCP sunucusu kimlik doğrulaması.
Not
Proje bağlantınızın kimliği olarak project_connection_id ayarlayın.
Ipucu
Add Tools kataloğu aracılığıyla Azure DevOps MCP Sunucusu'nu (önizleme) eklediğinizde, kuruluş bağlantısı adımı sırasında Azure DevOps kimlik doğrulaması yapar ve kimlik doğrulamasını proje bağlantısı olarak depolarsınız. Kuruluşa bağlanırken en az ayrıcalıklı erişimi kullanın ve kapsamları gözden geçirin.
Bir Döküm Aracı Kutusu MCP uç noktası kullandığınızda, Araç Kutusu kimlik doğrulamasını merkezi olarak yönetir. Araç Kutusu, paketteki tüm araçlar için çalışma zamanında kimlik bilgisi enjeksiyonu, token yenileme ve politika uygulama işlemlerini yönetir. Aracılar, DefaultAzureCredential gibi Microsoft Entra kimlik bilgilerini kullanarak doğrudan araç kutusu uç noktasında kimlik doğrulaması yapar, bu nedenle her aracının ayrı ayrı araç kimlik bilgilerini iletmesi gerekmez. Toolbox kimlik doğrulaması yapılandırması için bkz. Toolbox önkoşulları.
Microsoft dışı hizmetleri ve sunucuları kullanma konusunda dikkat edilmesi gerekenler
Bağlı olmayan Microsoft hizmetleri kullandığınızda hizmet sağlayıcısıyla aranızdaki koşullara tabisiniz. Microsoft olmayan bir hizmete bağlandığınızda, istem içeriği gibi verilerinizin bir bölümünü Microsoft olmayan hizmete geçirirsiniz veya uygulamanız Microsoft olmayan hizmetten veri alabilir. Microsoft dışındaki hizmetleri ve verileri kullanmanızdan ve bu kullanımla ilişkili tüm ücretlerden siz sorumlusunuz.
Microsoft değil üçüncü taraflar, bu makalede açıklanan MCP aracıyla kullanmaya karar vereceğiniz uzak MCP sunucularını oluşturur. Microsoft bu sunucuları test etmez veya doğrulamaz. Microsoft uzak MCP sunucularını kullanımınızla ilgili olarak size veya başkalarına karşı hiçbir sorumluluğu yoktur.
Foundry Agent Service'e eklediğiniz MCP sunucularını dikkatle gözden geçirin ve izleyin. Proxy'ler yerine güvenilen hizmet sağlayıcıları tarafından barındırılan sunuculara güvenin.
MCP aracı, uzak bir MCP sunucusunun ihtiyaç duyabileceği kimlik doğrulama anahtarları veya şemalar gibi özel üst bilgileri geçirmenizi sağlar. Uzak MCP sunucularıyla paylaştığınız tüm verileri gözden geçirin ve denetim amacıyla verileri günlüğe kaydedin. Verilerin saklanması ve konumu için Microsoft olmayan uygulamalara dikkat edin.
Not
Döküm Araç Takımları, üçüncü taraf MCP sunucularından farklıdır. Araç kutuları, Microsoft Foundry projenizde oluşturduğunuz ve yönettiğiniz kuruluş tarafından yönetilen kaynaklardır. Ancak, Araç Kutusu içeriklerini belirlerken araç seçimi, veri işleme ve uyumluluk hala sizin sorumluluğunuzdadır.
En iyi yöntemler
Araç kullanımı hakkında genel yönergeler için bkz. Microsoft Foundry Agent Service'de araçların kullanımı için en iyi uygulamalar.
MCP sunucularını kullanırken şu uygulamaları izleyin:
- kullanarak araçlara izin ver listesini kullanın
allowed_tools. - Yüksek riskli işlemler, özellikle de veri yazan veya kaynakları değiştiren araçlar için onay gerektirir.
- Onaylamadan önce istenen araç adını ve bağımsız değişkenlerini gözden geçirin.
- Denetim ve sorun giderme için günlük onayları ve araç çağrıları.
Ipucu
Add Tools kataloğu aracılığıyla Azure DevOps MCP Sunucusunu eklediğinizde, araç seçimi yapılandırması bu makalede açıklanan davranışla uyumlu olacak şekilde eşlenir. Katalog kullanıcı arabiriminde araçların bir alt kümesini seçmek, kodda liste allowed_tools belirtmekle eşdeğerdir.
MCP aracısıyla Python aracı oluşturma
Aracı oluşturmak ve işlevini çağırmak için aşağıdaki kod örneğini kullanın. .NET SDK şu anda önizleme aşamasındadır. Ayrıntılar için hızlı başlangıç bölümüne bakın.
Aşağıdaki örnekte, GitHub MCP sunucusunun aracı aracı olarak nasıl kullanılacağı gösterilmektedir.
import json
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, MCPTool
from openai.types.responses.response_input_param import McpApprovalResponse, ResponseInputParam
# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
MCP_CONNECTION_NAME = "my-mcp-connection"
# Create clients to call Foundry API
project = AIProjectClient(
endpoint=PROJECT_ENDPOINT,
credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()
# [START tool_declaration]
tool = MCPTool(
server_label="api-specs",
server_url="https://api.githubcopilot.com/mcp",
require_approval="always",
project_connection_id=MCP_CONNECTION_NAME,
)
# [END tool_declaration]
# Create a prompt agent with MCP tool capabilities
agent = project.agents.create_version(
agent_name="MyAgent7",
definition=PromptAgentDefinition(
model="gpt-5-mini",
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.conversations.create()
print(f"Created conversation (id: {conversation.id})")
# Send initial request that will trigger the MCP tool
response = openai.responses.create(
conversation=conversation.id,
input="What is my username in my GitHub profile?",
extra_body={"agent_reference": {"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" and item.id:
print("MCP approval requested")
print(f" Server: {item.server_label}")
print(f" Tool: {getattr(item, 'name', '<unknown>')}")
print(
f" Arguments: {json.dumps(getattr(item, 'arguments', None), indent=2, default=str)}"
)
# Approve only after you review the tool call.
# In production, implement your own approval UX and policy.
should_approve = (
input("Approve this MCP tool call? (y/N): ").strip().lower() == "y"
)
input_list.append(
McpApprovalResponse(
type="mcp_approval_response",
approve=should_approve,
approval_request_id=item.id,
)
)
# Send the approval response back to continue the agent's work
response = openai.responses.create(
input=input_list,
previous_response_id=response.id,
extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(f"Response: {response.output_text}")
# Clean up resources by deleting the agent version
project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)
print("Agent deleted")
Beklenen çıkış
Aşağıdaki örnekte, örneği çalıştırdığınızda beklenen çıkış gösterilmektedir:
Agent created (id: <agent-id>, name: MyAgent7, version: 1)
Created conversation (id: <conversation-id>)
Response: Your GitHub username is "example-username".
Agent deleted
MCP aracısıyla aracı oluşturma
Aşağıdaki örnekte, GitHub MCP sunucusunun aracı aracı olarak nasıl kullanılacağı gösterilmektedir. Örnek, aracı oluşturmak için zaman uyumlu yöntemler kullanır. Zaman uyumsuz metodlar için, GitHub'daki .NET için Azure SDK deposunda bulunan örnek koda bakın.
using System;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";
// Create project client to call Foundry API
AIProjectClient projectClient = new(
endpoint: new Uri(projectEndpoint),
tokenProvider: new DefaultAzureCredential());
// Create Agent with the `MCPTool`. Note that in this scenario
// GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval is used,
// which means that any calls to the MCP server must be approved.
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
Instructions = "You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.",
Tools = { ResponseTool.CreateMcpTool(
serverLabel: "api-specs",
serverUri: new Uri("https://gitmcp.io/Azure/azure-rest-api-specs"),
toolCallApprovalPolicy: new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval
)) }
};
AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
agentName: "myAgent",
options: new(agentDefinition));
// If the tool approval is required, the response item is
// of `McpToolCallApprovalRequestItem` type and contains all
// the information about tool call. This example checks that
// the server label is "api-specs" and approves the tool call.
// All other calls are denied because they should not occur for
// the current configuration.
ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);
CreateResponseOptions nextResponseOptions = new([ResponseItem.CreateUserMessageItem("Please summarize the Azure REST API specifications README")]);
ResponseResult latestResponse = null;
while (nextResponseOptions is not null)
{
latestResponse = responseClient.CreateResponse(nextResponseOptions);
nextResponseOptions = null;
foreach (ResponseItem responseItem in latestResponse.OutputItems)
{
if (responseItem is McpToolCallApprovalRequestItem mcpToolCall)
{
nextResponseOptions = new CreateResponseOptions()
{
PreviousResponseId = latestResponse.Id,
};
if (string.Equals(mcpToolCall.ServerLabel, "api-specs"))
{
Console.WriteLine($"Approval requested for {mcpToolCall.ServerLabel} (tool: {mcpToolCall.ToolName})");
Console.Write("Approve this MCP tool call? (y/N): ");
bool approved = string.Equals(Console.ReadLine(), "y", StringComparison.OrdinalIgnoreCase);
nextResponseOptions.InputItems.Add(ResponseItem.CreateMcpApprovalResponseItem(approvalRequestId: mcpToolCall.Id, approved: approved));
}
else
{
Console.WriteLine($"Rejecting unknown call {mcpToolCall.ServerLabel}...");
nextResponseOptions.InputItems.Add(ResponseItem.CreateMcpApprovalResponseItem(approvalRequestId: mcpToolCall.Id, approved: false));
}
}
}
}
// Output the final response from the agent.
Console.WriteLine(latestResponse.GetOutputText());
// Clean up resources by deleting the agent version.
projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
Beklenen çıkış
Aşağıdaki örnekte, örneği çalıştırdığınızda beklenen çıkış gösterilmektedir:
Approval requested for api-specs...
Response: The Azure REST API specifications repository contains the OpenAPI specifications for Azure services. It is
organized by service and includes guidelines for contributing new specifications. The repository is intended for use by developers building tools and services that interact with Azure APIs.
Proje bağlantısı kimlik doğrulaması ile MCP aracını kullanarak aracı oluşturma
Bu örnekte, GitHub MCP sunucusunda kimlik doğrulaması yapmayı ve aracı için bir araç olarak kullanmayı öğreneceksiniz. Örnek, aracı oluşturmak için zaman uyumlu yöntemler kullanır. Zaman uyumsuz metodlar için, GitHub'daki .NET için Azure SDK deposunda bulunan örnek koda bakın.
Proje bağlantısını ayarlama
Örneği çalıştırmadan önce:
- GitHub profilinizde oturum açın.
- Sağ üst köşedeki profil resmini seçin.
- Ayarlar'ı seçin.
- Sol panelde Geliştirici Ayarları ve Kişisel erişim belirteçleri Belirteçleri > (klasik) öğesini seçin.
- Üst kısımda Yeni belirteç oluştur'u seçin, parolanızı girin ve genel depoları okuyabilen bir belirteç oluşturun.
- Önemli: Belirteci kaydedin veya sayfa kapatıldıktan sonra belirteç yeniden gösterilemeyecek şekilde sayfayı açık tutun.
- Azure portalında Microsoft Dökümhane'yi açın.
- Sol panelde Yönetim merkezi'ni ve ardından Bağlı kaynaklar'ı seçin.
- Özel anahtar türü için yeni bağlantı oluşturun.
- Ad verin ve bir anahtar değer çifti ekleyin.
- Anahtar adını
Authorizationolarak ayarlayın ve değerinBearer your_github_tokenbiçiminde olması gerekir.
Ajanı oluşturmak için kod örneği
using System;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var projectEndpoint = "your_project_endpoint";
var mcpConnectionName = "my-mcp-connection";
// Create project client to call Foundry API
AIProjectClient projectClient = new(
endpoint: new Uri(projectEndpoint),
tokenProvider: new DefaultAzureCredential());
// Create an agent with the MCPTool. Note that, in this scenario,
// GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval is used.
// This means that any calls to the MCP server must be approved.
// The ProjectConnectionId property is then set on the McpTool
// so agent can authenticate with GitHub.
McpTool tool = ResponseTool.CreateMcpTool(
serverLabel: "api-specs",
serverUri: new Uri("https://api.githubcopilot.com/mcp"),
toolCallApprovalPolicy: new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval
));
tool.ProjectConnectionId = mcpConnectionName;
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
Instructions = "You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.",
Tools = { tool }
};
AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
agentName: "myAgent",
options: new(agentDefinition));
// If the tool approval is required, the response item is
// of McpToolCallApprovalRequestItem type and contains all
// the information about tool call. This example checks that
// the server label is "api-specs" and approves the tool call,
// All other calls are denied because they shouldn't happen given
// the current configuration.
ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);
CreateResponseOptions nextResponseOptions = new([ResponseItem.CreateUserMessageItem("What is my username in my GitHub profile?")]);
ResponseResult latestResponse = null;
while (nextResponseOptions is not null)
{
latestResponse = responseClient.CreateResponse(nextResponseOptions);
nextResponseOptions = null;
foreach (ResponseItem responseItem in latestResponse.OutputItems)
{
if (responseItem is McpToolCallApprovalRequestItem mcpToolCall)
{
nextResponseOptions = new()
{
PreviousResponseId = latestResponse.Id,
};
if (string.Equals(mcpToolCall.ServerLabel, "api-specs"))
{
Console.WriteLine($"Approval requested for {mcpToolCall.ServerLabel} (tool: {mcpToolCall.ToolName})");
Console.Write("Approve this MCP tool call? (y/N): ");
bool approved = string.Equals(Console.ReadLine(), "y", StringComparison.OrdinalIgnoreCase);
nextResponseOptions.InputItems.Add(ResponseItem.CreateMcpApprovalResponseItem(approvalRequestId: mcpToolCall.Id, approved: approved));
}
else
{
Console.WriteLine($"Rejecting unknown call {mcpToolCall.ServerLabel}...");
nextResponseOptions.InputItems.Add(ResponseItem.CreateMcpApprovalResponseItem(approvalRequestId: mcpToolCall.Id, approved: false));
}
}
}
}
// Output the final response from the agent.
Console.WriteLine(latestResponse.GetOutputText());
// Clean up resources by deleting the agent version.
projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
Beklenen çıkış
Aşağıdaki örnekte, örneği çalıştırdığınızda beklenen çıkış gösterilmektedir:
Approval requested for api-specs...
Response: Your GitHub username is "example-username".
MCP aracısıyla TypeScript'te aracı oluşturma
Aşağıdaki TypeScript örneği, MCP araç özellikleriyle aracı oluşturma, MCP onay iş akışlarını tetikleyen istekler gönderme, onay isteklerini işleme ve kaynakları temizleme işlemlerini gösterir. JavaScript sürümü için GitHub'daki JavaScript deposu için Azure SDK örnek kodu bölümüne bakın.
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import OpenAI from "openai";
import * as readline from "readline";
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
export async function main(): Promise<void> {
// Create clients to call Foundry API
const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
const openai = project.getOpenAIClient();
console.log("Creating agent with MCP tool...");
// Define MCP tool that connects to Azure REST API specifications GitHub repository
// The tool requires approval for each operation to ensure user control over external requests
const agent = await project.agents.createVersion("agent-mcp", {
kind: "prompt",
model: "gpt-5-mini",
instructions:
"You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.",
tools: [
{
type: "mcp",
server_label: "api-specs",
server_url: "https://gitmcp.io/Azure/azure-rest-api-specs",
require_approval: "always",
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);
// Create a conversation thread to maintain context across multiple interactions
console.log("\nCreating conversation...");
const conversation = await openai.conversations.create();
console.log(`Created conversation (id: ${conversation.id})`);
// Send initial request that will trigger the MCP tool to access Azure REST API specs
// This will generate an approval request since requireApproval="always"
console.log("\nSending request that will trigger MCP approval...");
const response = await openai.responses.create(
{
conversation: conversation.id,
input: "Please summarize the Azure REST API specifications Readme",
},
{
body: { agent: { name: agent.name, type: "agent_reference" } },
},
);
// Process any MCP approval requests that were generated
// When requireApproval="always", the agent will request permission before accessing external resources
const inputList: OpenAI.Responses.ResponseInputItem.McpApprovalResponse[] = [];
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
const ask = (q: string) => new Promise<string>((resolve) => rl.question(q, resolve));
for (const item of response.output) {
if (item.type === "mcp_approval_request") {
if (item.server_label === "api-specs" && item.id) {
console.log(`\nReceived MCP approval request (id: ${item.id})`);
console.log(` Server: ${item.server_label}`);
console.log(` Tool: ${item.name}`);
// Approve only after you review the tool call.
// In production, implement your own approval UX and policy.
const answer = (await ask("Approve this MCP tool call? (y/N): ")).trim().toLowerCase();
const approve = answer === "y";
inputList.push({
type: "mcp_approval_response",
approval_request_id: item.id,
approve,
});
}
}
}
rl.close();
console.log(`\nProcessing ${inputList.length} approval request(s)`);
console.log("Final input:");
console.log(JSON.stringify(inputList, null, 2));
// 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
console.log("\nSending approval response...");
const finalResponse = await openai.responses.create(
{
input: inputList,
previous_response_id: response.id,
},
{
body: { agent: { name: agent.name, type: "agent_reference" } },
},
);
console.log(`\nResponse: ${finalResponse.output_text}`);
// Clean up resources by deleting the agent version and conversation
// This prevents accumulation of unused resources in your project
console.log("\nCleaning up resources...");
await openai.conversations.delete(conversation.id);
console.log("Conversation deleted");
await project.agents.deleteVersion(agent.name, agent.version);
console.log("Agent deleted");
console.log("\nMCP sample completed!");
}
main().catch((err) => {
console.error("The sample encountered an error:", err);
});
Beklenen çıkış
Aşağıdaki örnekte, örneği çalıştırdığınızda beklenen çıkış gösterilmektedir:
Creating agent with MCP tool...
Agent created (id: <agent-id>, name: agent-mcp, version: 1)
Creating conversation...
Created conversation (id: <conversation-id>)
Sending request that will trigger MCP approval...
Received MCP approval request (id: <approval-request-id>)
Server: api-specs
Tool: get-readme
Processing 1 approval request(s)
Final input:
[
{
"type": "mcp_approval_response",
"approval_request_id": "<approval-request-id>",
"approve": true
}
]
Sending approval response...
Response: The Azure REST API specifications repository contains the OpenAPI specifications for Azure services. It is organized by service and includes guidelines for contributing new specifications. The repository is intended for use by developers building tools and services that interact with Azure APIs.
Cleaning up resources...
Conversation deleted
Agent deleted
MCP sample completed!
Proje bağlantısı kimlik doğrulaması ile MCP aracını kullanarak aracı oluşturma
Aşağıdaki TypeScript örneği, proje bağlantısı kimlik doğrulamasını kullanarak MCP aracı özellikleriyle aracı oluşturmayı, MCP onay iş akışlarını tetikleyen istekler göndermeyi, onay isteklerini işlemeyi ve kaynakları temizlemeyi gösterir. JavaScript sürümü için GitHub'daki JavaScript deposu için Azure SDK örnek kodu bölümüne bakın.
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import OpenAI from "openai";
import * as readline from "readline";
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const MCP_CONNECTION_NAME = "my-mcp-connection";
export async function main(): Promise<void> {
// Create clients to call Foundry API
const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
const openai = project.getOpenAIClient();
console.log("Creating agent with MCP tool using project connection...");
// Define MCP tool that connects to GitHub Copilot API with project connection authentication
// The project connection should have Authorization header configured with "Bearer <GitHub PAT token>"
// Token can be created at https://github.com/settings/personal-access-tokens/new
const agent = await project.agents.createVersion("agent-mcp-connection-auth", {
kind: "prompt",
model: "gpt-5-mini",
instructions: "Use MCP tools as needed",
tools: [
{
type: "mcp",
server_label: "api-specs",
server_url: "https://api.githubcopilot.com/mcp",
require_approval: "always",
project_connection_id: MCP_CONNECTION_NAME,
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);
// Create a conversation thread to maintain context across multiple interactions
console.log("\nCreating conversation...");
const conversation = await openai.conversations.create();
console.log(`Created conversation (id: ${conversation.id})`);
// Send initial request that will trigger the MCP tool
console.log("\nSending request that will trigger MCP approval...");
const response = await openai.responses.create(
{
conversation: conversation.id,
input: "What is my username in my GitHub profile?",
},
{
body: { agent: { name: agent.name, type: "agent_reference" } },
},
);
// Process any MCP approval requests that were generated
const inputList: OpenAI.Responses.ResponseInputItem.McpApprovalResponse[] = [];
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
const ask = (q: string) => new Promise<string>((resolve) => rl.question(q, resolve));
for (const item of response.output) {
if (item.type === "mcp_approval_request") {
if (item.server_label === "api-specs" && item.id) {
console.log(`\nReceived MCP approval request (id: ${item.id})`);
console.log(` Server: ${item.server_label}`);
console.log(` Tool: ${item.name}`);
// Approve only after you review the tool call.
// In production, implement your own approval UX and policy.
const answer = (await ask("Approve this MCP tool call? (y/N): ")).trim().toLowerCase();
const approve = answer === "y";
inputList.push({
type: "mcp_approval_response",
approval_request_id: item.id,
approve,
});
}
}
}
rl.close();
console.log(`\nProcessing ${inputList.length} approval request(s)`);
console.log("Final input:");
console.log(JSON.stringify(inputList, null, 2));
// 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
console.log("\nSending approval response...");
const finalResponse = await openai.responses.create(
{
input: inputList,
previous_response_id: response.id,
},
{
body: { agent: { name: agent.name, type: "agent_reference" } },
},
);
console.log(`\nResponse: ${finalResponse.output_text}`);
// Clean up resources by deleting the agent version and conversation
// This prevents accumulation of unused resources in your project
console.log("\nCleaning up resources...");
await openai.conversations.delete(conversation.id);
console.log("Conversation deleted");
await project.agents.deleteVersion(agent.name, agent.version);
console.log("Agent deleted");
console.log("\nMCP with project connection sample completed!");
}
main().catch((err) => {
console.error("The sample encountered an error:", err);
});
Beklenen çıkış
Aşağıdaki örnekte, örneği çalıştırdığınızda beklenen çıkış gösterilmektedir:
Creating agent with MCP tool using project connection...
Agent created (id: <agent-id>, name: agent-mcp-connection-auth, version: 1)
Creating conversation...
Created conversation (id: <conversation-id>)
Sending request that will trigger MCP approval...
Received MCP approval request (id: <approval-request-id>)
Server: api-specs
Tool: get-github-username
Processing 1 approval request(s)
Final input:
[
{
"type": "mcp_approval_response",
"approval_request_id": "<approval-request-id>",
"approve": true
}
]
Sending approval response...
Response: Your GitHub username is "example-username".
Cleaning up resources...
Conversation deleted
Agent deleted
MCP with project connection sample completed!
Java aracısında MCP araçlarını kullanma
bağımlılığını öğesinin pom.xmliçine ekleyin:
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-ai-agents</artifactId>
<version>2.0.0</version>
</dependency>
MCP aracısıyla aracı oluşturma
import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.AzureCreateResponseOptions;
import com.azure.ai.agents.models.McpTool;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
import java.util.Collections;
public class McpToolExample {
public static void main(String[] args) {
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
String projectEndpoint = "your_project_endpoint";
String mcpConnectionName = "my-mcp-connection";
AgentsClientBuilder builder = new AgentsClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.endpoint(projectEndpoint);
AgentsClient agentsClient = builder.buildAgentsClient();
ResponsesClient responsesClient = builder.buildResponsesClient();
// Create MCP tool with server label, URL, connection, and approval mode
McpTool mcpTool = new McpTool("api-specs")
.setServerUrl("https://gitmcp.io/Azure/azure-rest-api-specs")
.setProjectConnectionId(mcpConnectionName)
.setRequireApproval("always");
// Create agent with MCP tool
PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-5-mini")
.setInstructions("You are a helpful assistant that can use MCP tools.")
.setTools(Collections.singletonList(mcpTool));
AgentVersionDetails agent = agentsClient.createAgentVersion("mcp-agent", agentDefinition);
System.out.printf("Agent created: %s (version %s)%n", agent.getName(), agent.getVersion());
// Create a response
AgentReference agentReference = new AgentReference(agent.getName())
.setVersion(agent.getVersion());
Response response = responsesClient.createAzureResponse(
new AzureCreateResponseOptions().setAgentReference(agentReference),
ResponseCreateParams.builder()
.input("Summarize the Azure REST API specifications"));
System.out.println("Response: " + response.output());
// Clean up
agentsClient.deleteAgentVersion(agent.getName(), agent.getVersion());
}
}
Beklenen çıkış
Agent created: mcp-agent (version 1)
Response: [ResponseOutputItem containing MCP tool results ...]
REST API ile MCP aracını kullanma
Aşağıdaki örneklerde, MCP aracısıyla aracı oluşturma ve Yanıtlar API'sini kullanarak aracıyı çağırma gösterilmektedir. Yanıt type öğesi mcp_approval_request olarak ayarlanmış bir çıkış öğesi içeriyorsa, mcp_approval_response öğesi içeren bir izleme isteği gönderin.
Önkoşullar
Şu ortam değişkenlerini ayarlayın:
-
FOUNDRY_PROJECT_ENDPOINT: Proje uç noktası URL'niz. -
FOUNDRY_MODEL_DEPLOYMENT_NAME: Model dağıtımınızın adı. -
AGENT_TOKEN: Foundry için taşıyıcı kimlik doğrulama belirteci. -
MCP_PROJECT_CONNECTION_NAME(isteğe bağlı): MCP proje bağlantınızın adı.
Erişim belirteci alma:
export AGENT_TOKEN=$(az account get-access-token --scope "https://ai.azure.com/.default" --query accessToken -o tsv)
MCP sunucunuz kimlik doğrulaması gerekmiyorsa istek project_connection_id gövdesinden atla.
Not
REST API için önce Bağlantılar API'sini kullanarak bağlantı adından bağlantı kimliğini almanız, ardından kimliği MCP araç yapılandırmasına geçirmeniz gerekir.
Ipucu
MCP araç şeması ve onay öğeleri hakkında ayrıntılı bilgi için REST başvurusundaki OpenAI.MCPTool ve MCP onay öğesi türlerine bakın.
1. MCP aracısı oluşturma
curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/agents?api-version=v1" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AGENT_TOKEN" \
-d '{
"name": "<AGENT_NAME>-mcp",
"description": "MCP agent",
"definition": {
"kind": "prompt",
"model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
"instructions": "You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.",
"tools": [
{
"type": "mcp",
"server_label": "api-specs",
"server_url": "https://gitmcp.io/Azure/azure-rest-api-specs",
"require_approval": "never"
}
]
}
}'
Kimliği doğrulanmış bir MCP sunucusunu proje bağlantısıyla kullanmak için araç tanımına ekleyin "project_connection_id": "'$MCP_PROJECT_CONNECTION_NAME'" ve kimliği doğrulanmış sunucu uç noktasına (örneğin, server_url) geçinhttps://api.githubcopilot.com/mcp.
2. Yanıt oluşturma
curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AGENT_TOKEN" \
-d '{
"agent": {"type": "agent_reference", "name": "<AGENT_NAME>-mcp"},
"input": "Please summarize the Azure REST API specifications Readme"
}'
Eğer yanıt type öğesi mcp_approval_request olarak bir çıkış öğesi içeriyorsa, onay isteği öğesini id olarak APPROVAL_REQUEST_ID kopyalayın. Ayrıca üst düzey yanıtı id olarak PREVIOUS_RESPONSE_IDkopyalayın.
3. Onay yanıtı gönderme
MCP aracı onay gerektiriyorsa bir izleme isteği gönderin:
curl -X POST "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AGENT_TOKEN" \
-d '{
"previous_response_id": "'$PREVIOUS_RESPONSE_ID'",
"input": [
{
"type": "mcp_approval_response",
"approval_request_id": "'$APPROVAL_REQUEST_ID'",
"approve": true
}
]
}'
4. Kaynakları temizleme
Aracıyı silin:
curl -X DELETE "$FOUNDRY_PROJECT_ENDPOINT/agents/<AGENT_NAME>-mcp?api-version=v1" \
-H "Authorization: Bearer $AGENT_TOKEN"
Nasıl çalışır?
Foundry Agent Service'e uzak bir MCP sunucusu (mevcut bir MCP sunucusu uç noktası) getirmeniz gerekir. Birden çok uzak MCP sunucusunu araç olarak ekleyerek getirebilirsiniz. Her araç için, aynı aracı içinde benzersiz server_label bir değer ve uzak MCP sunucusuna işaret eden bir server_url değer sağlamanız gerekir. Foundry Agent Service'e hangi MCP sunucularını eklediğinizi dikkatle gözden geçirmeyi unutmayın.
Rastgele uzak MCP sunucularını URL ile bağlamaya ek olarak, bazı MCP sunucuları doğrudan Foundry Araç Ekle kataloğundan eklenebilir. Örneğin, Azure DevOps MCP Sunucusu (önizleme) katalog girdisi olarak kullanılabilir. Katalog girişleri, bağlantı kurulumunu basitleştirir ve bu makalede belgelenen onay ve denetim mekanizmalarıyla aynı hizaya getirilir.
MCP kullanma hakkında daha fazla bilgi için bkz:
- Model Bağlam Protokolü web sitesinde En İyi Güvenlik Yöntemleri.
- MCP uygulamalarında güvenlik risklerini anlama ve azaltma Microsoft Güvenlik Topluluk Blogu'nda.
MCP bağlantısını ayarlama
Aşağıdaki adımlarda, Foundry Aracı Hizmeti'nden uzak bir MCP sunucusuna bağlanma adımları özetlenmiştir:
- Bağlanmak istediğiniz GitHub MCP sunucusu gibi uzak MCP sunucusunu bulun. Aşağıdaki bilgileri kullanarak bir
mcparaçla Bir Foundry aracısı oluşturun veya güncelleştirin:-
server_url: MCP sunucusunun, örneğinhttps://api.githubcopilot.com/mcp/gibi, URL'si. -
server_label: Aracıya bu MCP sunucusunun benzersiz tanımlayıcısı, örneğingithub. -
allowed_tools: Bu ajanın erişebileceği ve kullanabileceği seçenekli bir araç listesi. Bu değeri sağlamazsanız, varsayılan değer MCP sunucusundaki tüm araçları içerir. -
require_approval: İsteğe bağlı olarak onay gerekip gerekmediğini belirleyin. Varsayılan değerdiralways. Desteklenen değerler şunlardır:-
always: Bir geliştiricinin her çağrı için onay sağlaması gerekir. Bir değer sağlamazsanız, bu varsayılan değerdir. -
never: Onay gerekmez. -
{"never":[<tool_name_1>, <tool_name_2>]}: Onay gerektirmeyen araçların listesini sağlarsınız. -
{"always":[<tool_name_1>, <tool_name_2>]}: Onay gerektiren araçların listesini sağlarsınız.
-
-
-
project_connection_id: MCP sunucusu için kimlik doğrulamasını ve diğer bağlantı ayrıntılarını depolayan proje bağlantı kimliği. - Model, onay gerektiren bir aracı MCP sunucunuzda çağırmaya çalışırsa,
mcp_approval_requestolarak bir yanıt çıkış öğesi türü alırsınız. Yanıt çıktı öğesinde, MCP sunucusundaki hangi aracın çağrıldığı ve geçirilecek bağımsız değişkenler hakkında daha fazla ayrıntı alabilirsiniz. Onay için bilinçli bir karar alabilmeniz için aracı ve argümanları gözden geçirin. -
previous_response_idkullanarak veapproveayarlayarak onayınızıtruearacısına gönderin.
Azure DevOps MCP Sunucusuna bağlanma
Azure DevOps MCP Sunucusu (önizleme), Foundry'de katalog girdisi olarak kullanılabilir. Eklemek için:
- Foundry portalında projenize erişin.
- Add Tools>Catalog öğesini seçin ve "Azure DevOps" araması yapın.
- Azure DevOps MCP Sunucusu (önizleme)'ı seçin ve Oluştur'i seçin.
- Azure DevOps kuruluşunuzun adını girin ve Connect öğesini seçin.
- Aracınıza hangi Azure DevOps araçlarının kullanıma sunmasını istediğinizi seçin. Araçların tam olarak nelere erişebileceğini denetlemek için bir araçlar alt kümesi seçebilirsiniz.
Bu katalog tabanlı kurulum, kod değişikliği gerektirmeden aracılar tarafından kullanılmak üzere MCP aracını oluşturur. Aracı üretim koduyla tümleştirmeden önce Foundry sohbet testi deneyiminde bağlantı ve araç davranışını doğrulayabilirsiniz.
Ipucu
Araç kutusu sürümü oluşturma: Döküm Aracı Kutuları sürüm oluşturmayı desteklediği için üretim aracılarını etkilemeden yeni bir sürümde yineleme yapabilirsiniz. Üretim aracıları için tüketici uç noktasını ({project_endpoint}/toolboxes/{name}/mcp?api-version=v1) kullanın; her zaman yükseltilen varsayılan sürüme hizmet eder. Tanıtım yapmadan önce test etmek için sürüme özgü uç noktayı ({project_endpoint}/toolboxes/{name}/versions/{version}/mcp?api-version=v1) kullanın. Aracı başına server_label benzersiz tutun, Toolbox sürümleri arasında geçiş yaparken bile. Ayrıntılar için bkz . Sürümü varsayılana yükseltme.
Bilinen sınırlamalar
- Akışsız MCP aracı arama zaman aşımı: Akışsız MCP araç çağrılarının zaman aşımı 100 saniyedir. MCP sunucunuzun yanıt vermesi 100 saniyeden uzun sürüyorsa çağrı başarısız olur. Zaman aşımlarını önlemek için MCP sunucunuzun bu sınır içinde yanıt verdiğinden emin olun. Kullanım örneğiniz daha uzun işleme süreleri gerektiriyorsa, sunucu tarafı mantığını iyileştirmeyi veya işlemi daha küçük adımlara ayırmayı göz önünde bulundurun.
- Özel MCP, Standart Aracı Kurulumu gerektirir: Özel MCP sunucu bağlantısı yalnızca özel ağ (BYO VNet) ile Standart Aracı Kurulumu ile kullanılabilir. Temel aracı kurulumu özel MCP uç noktalarını desteklemez.
- Private MCP barındırma: Ayrılmış bir MCP alt aðýndaki Azure Container Apps özel MCP sunucuları için test edilen yapılandırmadır. Özel MCP sunucu konağı olarak İşlev Uygulamaları veya Uygulama Hizmetleri çalışabilir, ancak şirket içinde doğrulanmaz.
Sık sorulan sorular ve hatalar
McP araçlarını Foundry Agent Service ile kullandığınızda aşağıdaki yaygın sorunlar oluşabilir:
"Geçersiz araç şeması":
Bu hata genellikle MCP sunucu tanımınız veya
anyOfiçeriyorsaallOfya da bir parametre birden çok değer türünü kabul ederse oluşur. MCP sunucu tanımınızı güncelleştirin ve yeniden deneyin.MCP sunucusundan "Yetkisiz" veya "Yasak":
MCP sunucusunun kimlik doğrulama yönteminizi desteklediğini doğrulayın ve proje bağlantınızda depolanan kimlik bilgilerini doğrulayın. GitHub için en az ayrıcalıklı belirteçleri kullanın ve bunları düzenli olarak döndürün.
Model hiçbir zaman MCP aracınızı çağırmaz:
Ajan yönergelerinizi onaylayın, araç kullanımını teşvik edin ve
server_label,server_urlveallowed_toolsdeğerlerini doğrulayın. Eğerallowed_toolsayarlarsanız, araç adının MCP sunucusunda sağlananla eşleştiğinden emin olun.Aracı, onaydan sonra hiçbir zaman devam etmez:
Özgün yanıt kimliğine ayarlanan
previous_response_idile bir takip isteği gönderdiğinizi veapproval_request_idolarak onay isteği öğesi kimliğini kullandığınızı onaylayın.
Yerel bir MCP sunucusu barındırma
Aracı Hizmeti çalışma zamanı yalnızca uzak bir MCP sunucu uç noktasını kabul eder. Yerel bir MCP sunucusundan araç eklemek istiyorsanız, uzak bir MCP sunucusu uç noktasını almak için Azure Container Apps veya Azure İşlevleri üzerinde kendi kendine barındırmanız gerekir.
Uzak uç nokta, sanal ağınızdaki genel uç nokta veya özel uç nokta olabilir. Özel MCP sunucuları için, Container App'inizi yalnızca iç giriş (--internal-only true) ile özel bir MCP alt ağına dağıtın. Kurulum ayrıntıları için bkz. Genel ve özel MCP sunucu uç noktaları .
Bulutta yerel MCP sunucularını barındırırken aşağıdaki faktörleri göz önünde bulundurun:
| Yerel MCP sunucusu kurulumu | Azure Container Apps'da barındırma | Azure İşlevleri'de barındırma |
|---|---|---|
| Taşıma | HTTP POST/GET uç noktaları gereklidir. | HTTP akış desteği gereklidir. |
| Kod değişiklikleri | Container yeniden derlenmesi gerekli. | Kök dizininde Azure İşlevleri'a özel yapılandırma dosyaları gereklidir. |
| Kimlik doğrulama | Özel kimlik doğrulaması uygulaması gerekiyor. | Yalnızca anahtar tabanlı. OAuth API Management gerektirir. |
| Dil | Linux kapsayıcılarında çalışan tüm diller (Python, Node.js, .NET, TypeScript, Go). | Python, Node.js, Java, yalnızca .NET. |
| Kapsayıcı gereksinimleri | Yalnızca Linux (linux/amd64). Ayrıcalıklı kapsayıcı yok. | Kapsayıcılı sunucular desteklenmez. |
| Bağımlılık | Tüm bağımlılıklar kapsayıcı görüntüsünde olmalıdır. | İşletim sistemi düzeyinde bağımlılıklar (Playwright gibi) desteklenmez. |
| Durum | Yalnızca durumsuz. | Yalnızca durumsuz. |
| UVX/NPX | Desteklenen. | Desteklenmez.
npx başlatma komutları desteklenmiyor. |
İlgili içerik
- Kod kullanarak aracıları kullanmaya başlama
- MCP sunucusu kimlik doğrulaması
- Model Bağlam Protokolü (MCP) sunucusu oluşturma ve kaydetme
- Foundry Aracı Hizmeti için özel ağ oluşturun
- Foundry için Private Link yapılandırma
- MCP aracı REST başvurusu
- MCP için En İyi Güvenlik Uygulamaları
- MCP uygulamalarında güvenlik risklerini anlama ve azaltma