ARACılarla MCP araçlarını kullanma

Model Bağlam Protokolü, 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.

Microsoft Agent Framework Model Bağlam Protokolü (MCP) sunucularıyla tümleştirmeyi destekleyerek aracılarınızın dış araçlara ve hizmetlere erişmesine olanak sağlar. Bu kılavuzda, bir MCP sunucusuna bağlanma ve aracınızdaki araçlarını kullanma gösterilmektedir.

Üçüncü taraf MCP sunucularını kullanma konusunda dikkat edilmesi gerekenler

Model Bağlam Protokolü sunucularını kullanımınız, sizinle hizmet sağlayıcısı arasındaki koşullara tabidir. Microsoft dışı bir hizmete bağlandığınızda, verilerinizin bir bölümü (istem içeriği gibi) Microsoft dışı hizmete geçirilir veya uygulamanız Microsoft dışı hizmetten veri alabilir. Microsoft dışı hizmetleri ve verileri ve bu kullanımla ilişkili tüm ücretleri kullanmak sizin sorumluluğunuzdadır.

Bu makalede açıklanan MCP aracıyla kullanmaya karar vereceğiniz uzak MCP sunucuları Microsoft tarafından değil üçüncü taraflarca oluşturulmuştur. Microsoft bu sunucuları test etmedi veya doğrulamadı. Microsoft'un uzak MCP sunucularını kullanımınızla ilgili olarak size veya başkalarına karşı hiçbir sorumluluğu yoktur.

Agent Framework tabanlı uygulamalarınıza eklediğiniz MCP sunucularını dikkatle gözden geçirmenizi ve izlemenizi öneririz. Ayrıca proxy'ler yerine güvenilen hizmet sağlayıcıları tarafından barındırılan sunuculara güvenmenizi öneririz.

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şılan tüm verileri gözden geçirmenizi ve denetim amacıyla verileri günlüğe kaydetmenizi öneririz. Verilerin saklanması ve konumları için Microsoft dışı uygulamalar hakkında bilgili olun.

Önemli

Üst bilgileri yalnızca her çalıştırmada tool_resources ekleyerek belirtebilirsiniz. Bu şekilde API anahtarlarını, OAuth erişim belirteçlerini veya diğer kimlik bilgilerini doğrudan isteğinize yerleştirebilirsiniz. Geçirdiğiniz başlıklar yalnızca geçerli yürütme için kullanılabilir ve kalıcı değildir.

MCP güvenliği hakkında daha fazla bilgi için bkz:

Model Bağlam Protokolü web sitesinde En İyi Güvenlik Yöntemleri.
Microsoft Güvenlik Topluluğu Blogu'nda MCP uygulamalarındaki güvenlik risklerini anlama ve azaltma.

Agent Framework'ün .NET sürümü, aracınızın MCP araçlarını çağırmasına izin vermek için resmi MCP C# SDK'sı ile birlikte kullanılabilir.

Aşağıdaki örnekte şunların nasıl yapılacağını gösterilmektedir:

kurulum ve MCP sunucusu
MCP Sunucusundan kullanılabilir araçların listesini alma
MCP araçlarını aracıya AIFunctioneklenebilmeleri için 'lere dönüştürün
İşlev çağrısını kullanarak aracıdan araçları çağırma

MCP İstemcisi Ayarlama

İlk olarak, istediğiniz MCP sunucusuna bağlanan bir MCP istemcisi oluşturun:

// Create an MCPClient for the GitHub server
await using var mcpClient = await McpClientFactory.CreateAsync(new StdioClientTransport(new()
{
    Name = "MCPServer",
    Command = "npx",
    Arguments = ["-y", "--verbose", "@modelcontextprotocol/server-github"],
}));

Bu örnekte:

Ad: MCP sunucu bağlantınız için kolay bir ad
Komut: MCP sunucusunu çalıştırmak için yürütülebilir dosya (burada bir Node.js paketi çalıştırmak için npx kullanılarak)
Bağımsız değişkenler: MCP sunucusuna geçirilen komut satırı bağımsız değişkenleri

Kullanılabilir Araçları Alma

Bağlandıktan sonra, MCP sunucusundan kullanılabilen araçların listesini alın:

// Retrieve the list of tools available on the GitHub server
var mcpTools = await mcpClient.ListToolsAsync().ConfigureAwait(false);

yöntemi, ListToolsAsync() MCP sunucusunun kullanıma sunulan bir araç koleksiyonu döndürür. Bu araçlar otomatik olarak aracınız tarafından kullanılabilecek AITool nesnelerine dönüştürülür.

MCP Araçları ile Aracı Oluşturma

Aracınızı oluşturun ve başlatma sırasında MCP araçlarını sağlayın:

AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint),
    new DefaultAzureCredential())
     .GetChatClient(deploymentName)
     .AsAIAgent(
         instructions: "You answer questions related to GitHub repositories only.",
         tools: [.. mcpTools.Cast<AITool>()]);

Uyarı

DefaultAzureCredential geliştirme için uygundur ancak üretimde dikkatli bir şekilde dikkate alınması gerekir. Üretimde gecikme sorunları, istenmeyen kimlik bilgisi yoklama ve geri dönüş mekanizmalarından kaynaklanan olası güvenlik risklerini önlemek için belirli bir kimlik bilgisi (ör ManagedIdentityCredential. ) kullanmayı göz önünde bulundurun.

Önemli noktalar:

Yönergeler: MCP araçlarınızın özellikleriyle uyumlu net yönergeler sağlayın
Araçlar: MCP araçlarını nesnelere atama AITool ve araçlar dizisine yayma
Aracı, MCP sunucusu tarafından sağlanan tüm araçlara otomatik olarak erişebilir

Ajanı Kullanma

Aracınız yapılandırıldıktan sonra kullanıcı isteklerini yerine getirmek için otomatik olarak MCP araçlarını kullanabilir:

// Invoke the agent and output the text result
Console.WriteLine(await agent.RunAsync("Summarize the last four commits to the microsoft/semantic-kernel repository?"));

Aracı:

Kullanıcının isteğini analiz etme
Hangi MCP araçlarının gerekli olduğunu belirleme
MCP sunucusu aracılığıyla uygun araçları çağırma
Sonuçları tutarlı bir yanıt halinde sentezleyin

Ortam Yapılandırması

Gerekli ortam değişkenlerini ayarladığınızdan emin olun:

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ??
    throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

Kaynak Yönetimi

MCP istemci kaynaklarını her zaman düzgün bir şekilde atın:

await using var mcpClient = await McpClientFactory.CreateAsync(...);

kullanımı await using , MCP istemci bağlantısının kapsam dışına çıktığında düzgün bir şekilde kapatılmasını sağlar.

Yaygın MCP Sunucuları

Popüler MCP sunucuları şunlardır:

@modelcontextprotocol/server-github: GitHub depolarına ve verilerine erişme
@modelcontextprotocol/server-filesystem: Dosya sistemi işlemleri
@modelcontextprotocol/server-sqlite: SQLite veritabanı erişimi

Her sunucu, aracınızın işlevselliğini genişleten farklı araçlar ve özellikler sağlar. Bu tümleştirme aracılarınızın dış veri ve hizmetlere sorunsuz bir şekilde erişmesine olanak tanırken Model Bağlam Protokolü'nin güvenlik ve standartlaştırma avantajlarını korur.

Bu örneği çalıştırmaya ilişkin tam kaynak kodu ve yönergeler adresinde https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/GettingStarted/ModelContextProtocol/Agent_MCP_Serverbulunabilir.

Tip

Çalıştırılabilir örneklerin tamamı için .NET örneklerine bakın.

Bu, aracılarınızın dış araçlara ve hizmetlere sorunsuz bir şekilde erişmesini sağlar.

MCP Araç Türleri

Agent Framework üç tür MCP bağlantısını destekler:

MCPStdioTool - Yerel MCP Sunucuları

Standart giriş/çıkış kullanarak yerel işlemler olarak çalışan MCP sunucularına bağlanmak için kullanın MCPStdioTool :

import asyncio
from agent_framework import Agent, MCPStdioTool
from agent_framework.openai import OpenAIChatClient

async def local_mcp_example():
    """Example using a local MCP server via stdio."""
    async with (
        MCPStdioTool(
            name="calculator",
            command="uvx",
            args=["mcp-server-calculator"]
        ) as mcp_server,
        Agent(
            chat_client=OpenAIChatClient(),
            name="MathAgent",
            instructions="You are a helpful math assistant that can solve calculations.",
        ) as agent,
    ):
        result = await agent.run(
            "What is 15 * 23 + 45?",
            tools=mcp_server
        )
        print(result)

if __name__ == "__main__":
    asyncio.run(local_mcp_example())

MCPStreamableHTTPTool - HTTP/SSE MCP Sunucuları

Server-Sent Olayları ile HTTP üzerinden MCP sunucularına bağlanmak için kullanın MCPStreamableHTTPTool :

import asyncio
from agent_framework import Agent, MCPStreamableHTTPTool
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import AzureCliCredential

async def http_mcp_example():
    """Example using an HTTP-based MCP server."""
    async with (
        AzureCliCredential() as credential,
        MCPStreamableHTTPTool(
            name="Microsoft Learn MCP",
            url="https://learn.microsoft.com/api/mcp",
            headers={"Authorization": "Bearer your-token"},
        ) as mcp_server,
        Agent(
            chat_client=AzureAIAgentClient(async_credential=credential),
            name="DocsAgent",
            instructions="You help with Microsoft documentation questions.",
        ) as agent,
    ):
        result = await agent.run(
            "How to create an Azure storage account using az cli?",
            tools=mcp_server
        )
        print(result)

if __name__ == "__main__":
    asyncio.run(http_mcp_example())

MCPWebsocketTool - WebSocket MCP Sunucuları

WebSocket bağlantıları üzerinden MCP sunucularına bağlanmak için kullanın MCPWebsocketTool :

import asyncio
from agent_framework import Agent, MCPWebsocketTool
from agent_framework.openai import OpenAIChatClient

async def websocket_mcp_example():
    """Example using a WebSocket-based MCP server."""
    async with (
        MCPWebsocketTool(
            name="realtime-data",
            url="wss://api.example.com/mcp",
        ) as mcp_server,
        Agent(
            chat_client=OpenAIChatClient(),
            name="DataAgent",
            instructions="You provide real-time data insights.",
        ) as agent,
    ):
        result = await agent.run(
            "What is the current market status?",
            tools=mcp_server
        )
        print(result)

if __name__ == "__main__":
    asyncio.run(websocket_mcp_example())

Popüler MCP Sunucuları

Python Agent Framework ile kullanabileceğiniz yaygın MCP sunucuları:

Hesap Makinesi: uvx mcp-server-calculator - Matematiksel hesaplamalar
Dosya Sistemi: uvx mcp-server-filesystem - Dosya sistemi işlemleri
GitHub: npx @modelcontextprotocol/server-github - GitHub deposu erişimi
SQLite: uvx mcp-server-sqlite - Veritabanı işlemleri

Her sunucu, model bağlam protokolünün güvenlik ve standartlaştırma avantajlarını korurken aracınızın işlevselliğini genişleten farklı araçlar ve özellikler sağlar.

Tam örnek

# Copyright (c) Microsoft. All rights reserved.

import os

from agent_framework import Agent, MCPStreamableHTTPTool
from agent_framework.openai import OpenAIResponsesClient
from httpx import AsyncClient

"""
MCP Authentication Example

This example demonstrates how to authenticate with MCP servers using API key headers.

For more authentication examples including OAuth 2.0 flows, see:
- https://github.com/modelcontextprotocol/python-sdk/tree/main/examples/clients/simple-auth-client
- https://github.com/modelcontextprotocol/python-sdk/tree/main/examples/servers/simple-auth
"""


async def api_key_auth_example() -> None:
    """Example of using API key authentication with MCP server."""
    # Configuration
    mcp_server_url = os.getenv("MCP_SERVER_URL", "your-mcp-server-url")
    api_key = os.getenv("MCP_API_KEY")

    # Create authentication headers
    # Common patterns:
    # - Bearer token: "Authorization": f"Bearer {api_key}"
    # - API key header: "X-API-Key": api_key
    # - Custom header: "Authorization": f"ApiKey {api_key}"
    auth_headers = {
        "Authorization": f"Bearer {api_key}",
    }

    # Create HTTP client with authentication headers
    http_client = AsyncClient(headers=auth_headers)

    # Create MCP tool with the configured HTTP client
    async with (
        MCPStreamableHTTPTool(
            name="MCP tool",
            description="MCP tool description",
            url=mcp_server_url,
            http_client=http_client,  # Pass HTTP client with authentication headers
        ) as mcp_tool,
        Agent(
            client=OpenAIResponsesClient(),
            name="Agent",
            instructions="You are a helpful assistant.",
            tools=mcp_tool,
        ) as agent,
    ):
        query = "What tools are available to you?"
        print(f"User: {query}")
        result = await agent.run(query)
        print(f"Agent: {result.text}")

Aracıyı MCP Sunucusu Olarak Ortaya Çıkarma

Bir aracıyı MCP sunucusu olarak kullanıma sunarak MCP uyumlu herhangi bir istemci (VS Code GitHub Copilot Aracıları veya diğer aracılar gibi) tarafından araç olarak kullanılmasını sağlayabilirsiniz. Aracının adı ve açıklaması MCP sunucusu meta verileri olur.

aracını kullanarak .AsAIFunction()bir işlev aracısında sarmalayın, bir McpServerToololuşturun ve bir MCP sunucusuna kaydedin:

using System;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using ModelContextProtocol.Server;

// Create the agent
AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new AzureCliCredential())
        .GetChatClient("gpt-4o-mini")
        .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");

// Convert the agent to an MCP tool
McpServerTool tool = McpServerTool.Create(agent.AsAIFunction());

// Set up the MCP server over stdio
HostApplicationBuilder builder = Host.CreateEmptyApplicationBuilder(settings: null);
builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithTools([tool]);

await builder.Build().RunAsync();

Gerekli NuGet paketlerini yükleyin:

dotnet add package Microsoft.Extensions.Hosting --prerelease
dotnet add package ModelContextProtocol --prerelease

Aracıyı MCP sunucusu olarak kullanıma açmak için çağırın .as_mcp_server() :

from agent_framework.openai import OpenAIResponsesClient
from typing import Annotated

def get_specials() -> Annotated[str, "Returns the specials from the menu."]:
    return "Special Soup: Clam Chowder, Special Salad: Cobb Salad"

# Create an agent with tools
agent = OpenAIResponsesClient().as_agent(
    name="RestaurantAgent",
    description="Answer questions about the menu.",
    tools=[get_specials],
)

# Expose the agent as an MCP server
server = agent.as_mcp_server()

STANDART girişi/çıkışı dinlemek için MCP sunucusunu ayarlayın:

import anyio
from mcp.server.stdio import stdio_server

async def run():
    async with stdio_server() as (read_stream, write_stream):
        await server.run(read_stream, write_stream, server.create_initialization_options())

if __name__ == "__main__":
    anyio.run(run)

Sonraki Adımlar

İş akışlarını Aracı olarak kullanma

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-02-13