Aracıları Model Bağlam Protokolü sunucularına bağlama

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:

  1. GitHub profilinizde oturum açın.
  2. Sağ üst köşedeki profil resmini seçin.
  3. Ayarlar'ı seçin.
  4. Sol panelde Geliştirici Ayarları ve Kişisel erişim belirteçleri Belirteçleri > (klasik) öğesini seçin.
  5. Ü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.
  6. Azure portalında Microsoft Dökümhane'yi açın.
  7. Sol panelde Yönetim merkezi'ni ve ardından Bağlı kaynaklar'ı seçin.
  8. Özel anahtar türü için yeni bağlantı oluşturun.
  9. Ad verin ve bir anahtar değer çifti ekleyin.
  10. Anahtar adını Authorization olarak ayarlayın ve değerin Bearer your_github_token biç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:

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:

  1. Bağlanmak istediğiniz GitHub MCP sunucusu gibi uzak MCP sunucusunu bulun. Aşağıdaki bilgileri kullanarak bir mcp araçla Bir Foundry aracısı oluşturun veya güncelleştirin:
    1. server_url: MCP sunucusunun, örneğin https://api.githubcopilot.com/mcp/ gibi, URL'si.
    2. server_label: Aracıya bu MCP sunucusunun benzersiz tanımlayıcısı, örneğin github.
    3. 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.
    4. require_approval: İsteğe bağlı olarak onay gerekip gerekmediğini belirleyin. Varsayılan değerdir always. 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.
  2. 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.
  3. Model, onay gerektiren bir aracı MCP sunucunuzda çağırmaya çalışırsa, mcp_approval_request olarak 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.
  4. previous_response_id kullanarak ve approve ayarlayarak onayınızı true aracı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:

  1. Foundry portalında projenize erişin.
  2. Add Tools>Catalog öğesini seçin ve "Azure DevOps" araması yapın.
  3. Azure DevOps MCP Sunucusu (önizleme)'ı seçin ve Oluştur'i seçin.
  4. Azure DevOps kuruluşunuzun adını girin ve Connect öğesini seçin.
  5. 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çeriyorsa allOf ya 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_url ve allowed_tools değerlerini doğrulayın. Eğer allowed_tools ayarlarsanı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_id ile bir takip isteği gönderdiğinizi ve approval_request_id olarak 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.