Menggunakan alat MCP dengan Agen

Protokol Konteks Model adalah standar terbuka yang menentukan bagaimana aplikasi menyediakan alat dan data kontekstual ke model bahasa besar (LLM). Ini memungkinkan integrasi alat eksternal yang konsisten dan dapat diskalakan ke dalam alur kerja model.

Microsoft Agent Framework mendukung integrasi dengan server Protokol Konteks Model (MCP), memungkinkan agen Anda mengakses alat dan layanan eksternal. Panduan ini menunjukkan cara terhubung ke server MCP dan menggunakan alatnya dalam agen Anda.

Pertimbangan untuk menggunakan server MCP pihak ketiga

Penggunaan Server Protokol Konteks Model Anda tunduk pada persyaratan antara Anda dan penyedia layanan. Saat Anda tersambung ke layanan non-Microsoft, beberapa data Anda (seperti konten permintaan) diteruskan ke layanan non-Microsoft, atau aplikasi Anda mungkin menerima data dari layanan non-Microsoft. Anda bertanggung jawab atas penggunaan layanan dan data non-Microsoft, bersama dengan biaya apa pun yang terkait dengan penggunaan tersebut.

Server MCP jarak jauh yang Anda putuskan untuk digunakan dengan alat MCP yang dijelaskan dalam artikel ini dibuat oleh pihak ketiga, bukan Microsoft. Microsoft belum menguji atau memverifikasi server ini. Microsoft tidak bertanggung jawab kepada Anda atau orang lain sehubungan dengan penggunaan Server MCP jarak jauh apa pun.

Kami menyarankan agar Anda meninjau dan melacak server MCP apa yang Anda tambahkan ke aplikasi berbasis Agent Framework Anda. Kami juga menyarankan agar Anda mengandalkan server yang dihosting oleh penyedia layanan tepercaya itu sendiri daripada proksi.

Alat MCP memungkinkan Anda meneruskan header kustom, seperti kunci autentikasi atau skema, yang mungkin diperlukan server MCP jarak jauh. Sebaiknya tinjau semua data yang dibagikan dengan server MCP jarak jauh dan Anda mencatat data untuk tujuan audit. Perhatikan praktik retensi dan lokasi data yang tidak menggunakan Microsoft.

Penting

Anda hanya dapat menentukan header dengan menyertakannya dalam tool_resources di setiap eksekusi. Dengan cara ini, Anda dapat menempatkan kunci API, token akses OAuth, atau kredensial lainnya langsung dalam permintaan Anda. Header yang Anda masukkan hanya tersedia selama proses berjalan dan tidak disimpan.

Untuk informasi selengkapnya tentang keamanan MCP, lihat:

Praktik Terbaik Keamanan di situs web Protokol Konteks Model.
Memahami dan mengurangi risiko keamanan dalam implementasi MCP di Blog Komunitas Keamanan Microsoft.

Versi .NET dari Agent Framework dapat digunakan bersama dengan MCP C# SDK resmi untuk memungkinkan agen Anda memanggil alat MCP.

Contoh berikut menunjukkan cara:

Menyiapkan dan server MCP
Mengambil daftar alat yang tersedia dari Server MCP
Mengonversi alat MCP menjadi AIFunction's sehingga dapat ditambahkan ke agen
Memanggil alat dari agen menggunakan panggilan fungsi

Menyiapkan Klien MCP

Pertama, buat klien MCP yang terhubung ke server MCP yang Anda inginkan:

// 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"],
}));

Dalam contoh ini:

Nama: Nama yang mudah diingat untuk koneksi server MCP Anda
Perintah: Executable untuk menjalankan server MCP (di sini menggunakan npx untuk menjalankan paket Node.js)
Argumen: Argumen baris perintah diteruskan ke server MCP

Mengambil Alat yang Tersedia

Setelah tersambung, ambil daftar alat yang tersedia dari server MCP:

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

Metode ini ListToolsAsync() mengembalikan kumpulan alat yang diekspos server MCP. Alat-alat ini secara otomatis dikonversi ke objek AITool yang dapat digunakan oleh agen Anda.

Membuat Agen dengan Alat MCP

Buat agen Anda dan berikan alat MCP selama inisialisasi:

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

Peringatan

DefaultAzureCredential nyaman untuk pengembangan tetapi membutuhkan pertimbangan yang cermat dalam produksi. Dalam produksi, pertimbangkan untuk menggunakan kredensial tertentu (misalnya, ManagedIdentityCredential) untuk menghindari masalah latensi, pemeriksaan kredensial yang tidak diinginkan, dan potensi risiko keamanan dari mekanisme fallback.

Poin utama:

Petunjuk: Berikan instruksi yang jelas yang selaras dengan kemampuan alat MCP Anda
Alat: Mentransmisikan alat MCP ke AITool objek dan menyebarkannya ke dalam array alat
Agen akan secara otomatis memiliki akses ke semua alat yang disediakan oleh server MCP

Menggunakan Agen

Setelah dikonfigurasi, agen Anda dapat secara otomatis menggunakan alat MCP untuk memenuhi permintaan pengguna:

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

Agen akan:

Menganalisis permintaan pengguna
Menentukan alat MCP mana yang diperlukan
Memanggil alat yang sesuai melalui server MCP
Mensintesis hasil menjadi respons koheren

Konfigurasi Lingkungan

Pastikan untuk menyiapkan variabel lingkungan yang diperlukan:

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";

Manajemen Sumber Daya

Selalu buang sumber daya klien MCP dengan benar:

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

Menggunakan await using memastikan koneksi klien MCP ditutup dengan benar ketika keluar dari cakupan.

Server MCP Umum

Server MCP populer meliputi:

@modelcontextprotocol/server-github: Mengakses repositori dan data GitHub
@modelcontextprotocol/server-filesystem: Operasi sistem file
@modelcontextprotocol/server-sqlite: Akses database SQLite

Setiap server menyediakan berbagai alat dan kemampuan yang memperluas fungsionalitas agen Anda. Integrasi ini memungkinkan agen Anda untuk mengakses data dan layanan eksternal dengan lancar sambil mempertahankan manfaat keamanan dan standarisasi Protokol Konteks Model.

Petunjuk / Saran

Kode sumber lengkap dan instruksi untuk menjalankan sampel ini tersedia di https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/02-agents/ModelContextProtocol/Agent_MCP_Server.

Ini memungkinkan agen Anda mengakses alat dan layanan eksternal dengan mulus.

Nota

Pada penginstalan Python minimal, dukungan MCP mungkin perlu diinstal secara manual. Instal mcp --pre untuk menggunakan MCPStdioTool, MCPStreamableHTTPTool, atau Agent.as_mcp_server(). Instal mcp[ws] --pre jika Anda juga membutuhkan MCPWebsocketTool.

Jenis Alat MCP

Agent Framework mendukung tiga jenis koneksi MCP:

MCPStdioTool - Server MCP Lokal

Gunakan MCPStdioTool untuk menyambungkan ke server MCP yang berjalan sebagai proses lokal menggunakan input/output standar:

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(
            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 - Server HTTP/SSE MCP

Gunakan MCPStreamableHTTPTool untuk menyambungkan ke server MCP melalui HTTP dengan peristiwa Server-Sent:

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

async def http_mcp_example():
    """Example using an HTTP-based MCP server."""
    async with AzureCliCredential() as credential:
        client = FoundryChatClient(credential=credential)
        async with (
            MCPStreamableHTTPTool(
                name="Microsoft Learn MCP",
                url="https://learn.microsoft.com/api/mcp",
            ) as mcp_server,
            Agent(
                client=client,
                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())

Untuk titik akhir HTTP yang diautentikasi, lebih suka header_provider bersama dengan function_invocation_kwargs sehingga rahasia tetap dalam konteks runtime daripada dipanggang ke klien HTTP bersama.

MCPWebsocketTool - Server MCP WebSocket

Gunakan MCPWebsocketTool untuk menyambungkan ke server MCP melalui koneksi WebSocket:

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(
            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())

Server MCP Populer

Server MCP umum yang dapat Anda gunakan dengan Python Agent Framework:

Kalkulator: uvx mcp-server-calculator - Komputasi matematika
Sistem file: uvx mcp-server-filesystem - Operasi sistem file
GitHub: npx @modelcontextprotocol/server-github - Akses repositori GitHub
SQLite: uvx mcp-server-sqlite - Operasi database

Setiap server menyediakan berbagai alat dan kemampuan yang memperluas fungsionalitas agen Anda sambil mempertahankan manfaat keamanan dan standarisasi Protokol Konteks Model.

Contoh lengkap

# Copyright (c) Microsoft. All rights reserved.

import asyncio
import os

from agent_framework import Agent, MCPStreamableHTTPTool
from agent_framework.openai import OpenAIChatClient

"""
MCP Authentication Example

This example demonstrates the runtime `header_provider` pattern for authenticating with MCP servers.

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."""
    mcp_server_url = os.getenv("MCP_SERVER_URL", "your-mcp-server-url")
    api_key = os.getenv("MCP_API_KEY")
    if not api_key:
        raise ValueError("MCP_API_KEY environment variable must be set.")

    async with Agent(
        client=OpenAIChatClient(),
        name="Agent",
        instructions="You are a helpful assistant.",
        tools=MCPStreamableHTTPTool(
            name="MCP tool",
            description="MCP tool description",
            url=mcp_server_url,
            header_provider=lambda kwargs: {"Authorization": f"Bearer {kwargs['mcp_api_key']}"},
        ),
    ) as agent:
        query = "What tools are available to you?"
        print(f"User: {query}")
        result = await agent.run(
            query,
            function_invocation_kwargs={"mcp_api_key": api_key},
        )
        print(f"Agent: {result.text}")

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

Mengekspos Agen sebagai Server MCP

Anda dapat mengekspos agen sebagai server MCP, memungkinkannya digunakan sebagai alat oleh klien yang kompatibel dengan MCP (seperti Agen GitHub Copilot Visual Studio Code atau agen lain). Nama dan deskripsi agen menjadi metadata server MCP.

Bungkus agen dalam alat fungsi menggunakan .AsAIFunction(), buat McpServerTool, dan daftarkan dengan server MCP:

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

// Create the agent
AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
        .AsAIAgent(
            model: "gpt-4o-mini",
            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();

Peringatan

Instal paket NuGet yang diperlukan:

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

Panggil .as_mcp_server() agen untuk mengeksposnya sebagai server MCP:

Nota

Python agent.as_mcp_server() juga tergantung pada paket opsional mcp . Jika Anda menggunakan penginstalan berbasis ramping/inti, jalankan pip install mcp --pre terlebih dahulu.

from agent_framework.openai import OpenAIChatClient
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 = OpenAIChatClient().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()

Siapkan server MCP untuk mendengarkan input/output standar:

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)

Langkah selanjutnya

Percakapan & Memori

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-02