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 terhubung 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. Memahami praktik non-Microsoft terkait retensi dan lokasi data.

Penting

Anda dapat menentukan header per-eksekusi dengan menyertakannya dalam sumber daya alat di setiap eksekusi, atau mengonfigurasi header_provider pada alat MCP lokal Python. Tinjau kunci API, token akses OAuth, atau kredensial lain yang dibagikan dengan server MCP jarak jauh.

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:

using ModelContextProtocol.Client;

// Create an MCPClient for the GitHub server
await using var mcpClient = await McpClient.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:

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

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

Warning

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-poin penting:

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 McpClient.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.

Tip

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

Klien HTTP yang MCPStreamableHTTPTool membuat tidak mempertahankan cookie respons. Jika server memerlukan cookie untuk autentikasi, sesi, atau afinitas load balancer, lewati yang dikonfigurasi httpx.AsyncClient melalui http_client=. Klien yang disediakan mempertahankan perilaku cookie-nya dan tetap dimiliki pemanggil. Cakupan klien pembawa cookie dan sesi alat MCP-nya ke satu prinsipal yang diautentikasi.

Untuk titik akhir HTTP yang diautentikasi, gunakan static_headers untuk kredensial tetap atau header_provider untuk nilai yang berasal dari setiap eksekusi. Kedua jalur menambahkan header hanya untuk permintaan asal yang dikonfigurasi dan menghapusnya dari pengalihan lintas asal. Header tetap disalin saat alat dibuat dan tidak membuat serialisasi panggilan bersamaan. Ketika kedua opsi menyediakan header yang sama, nilai dinamis dari header_provider diutamakan.

Selama panggilan alat yang dihasilkan, header_provider hanya menerima host function_invocation_kwargseksekusi . Ini tidak menerima argumen alat yang disediakan model, bahkan ketika argumen model memiliki nama yang sama. Panggilan langsung call_tool(...) meneruskan argumen kata kunci yang disediakan pemanggilnya ke penyedia. Nilai model masih dapat diutamakan dalam argumen alat keluar yang digabungkan secara terpisah, tetapi tidak mengontrol header autentikasi.

Header tetap dan dinamis bersama-sama membentuk identitas efektif sesi HTTP. Nama header dibandingkan secara tidak peka huruf besar/kecil, sementara nilai tetap peka huruf besar/kecil. Argumen kata kunci runtime juga memenuhi syarat untuk argumen alat keluar ketika skema server mengizinkan nama yang sama. Untuk menjauhkan kredensial dari argumen alat, tangkap di penyedia melalui penutupan atau ContextVar, gunakan static_headers, atau berikan klien HTTP kustom.

Sesi yang dimiliki kerangka kerja mengikat identitas efektif ini saat terhubung. Jika eksekusi nanti menghasilkan identitas yang berbeda, alat akan terhubung kembali sebelum mengirim alat panggilan dan me-refresh alat yang diturunkan sesi dan meminta penemuan. Inisialisasi, penemuan, ping latar belakang, dan permintaan seumur hidup koneksi lainnya terus menggunakan header yang terikat ke sesi tersebut.

Sesi yang disediakan penelepon tetap dimiliki pemanggil. Karena pembungkus tidak dapat membuat atau menyambungkan kembali identitas yang tidak diketahui untuk sesi tersebut, resolusi header dinamis dengan identitas yang tidak diketahui ditolak. Identitas yang diubah juga ditolak; gunakan instans alat terkelola kerangka kerja terpisah.

Jika alat terhubung dengan bersemangat sebelum dijalankan, penyedia menerima pemetaan kosong untuk permintaan seumur hidup koneksi. Ambil atau refresh kredensial waktu konstruksi di penyedia untuk kasus ini. Jika kredensial hanya tiba pada waktu proses, teruskan alat run(tools=[...]) yang tidak terhubung dengan function_invocation_kwargs sehingga eksekusi membuat koneksi.

Dari KeyError penyedia ditoleransi hanya ketika tidak ada seeded eksekusi koneksi, dan permintaan berlanjut tanpa header penyedia. Setelah menjalankan seed koneksi, kunci yang hilang adalah kesalahan konfigurasi dan pengecualian muncul.

Pilih alat dengan nama yang tidak ambigu

Saat Anda mengatur atau mencantumkan allowed_tools alat di approval_mode, gunakan nama alat jarak jauh mentah atau nama awalan yang tidak ambigu. Jika satu nama yang dikonfigurasi cocok dengan beberapa nama jarak jauh mentah setelah normalisasi, Agent Framework akan menaikkan ToolExecutionException. Gunakan nama mentah atau perubahan tool_name_prefix yang tepat untuk membuat nama lokal unik.

Penghentian pengambilan sampel MCP

Warning

Pengambilan sampel MCP yang dimulai server dan sampling_callback tidak digunakan lagi pada versi spesifikasi MCP 2026-07-28 dan dihapus tidak lebih dari 2027-07-28. Jangan bangun integrasi baru pada fitur ini. Server MCP harus memanggil API penyedia model secara langsung.

Mengontrol retensi payload Host

Ketika transportasi Host, seperti AG-UI, mengonsumsi hasil alat MCP, Agent Framework mempertahankan hasil JSON-safe lengkap secara terpisah dari nilai yang menghadap model yang diurai. Ini memungkinkan Host untuk menerima bidang seperti structuredContent tanpa menambahkan data khusus Host ke riwayat model.

Gunakan tool_result_content pada transportasi MCP apa pun untuk memilih nilai yang terlihat model saat hasil berisi dan contentstructuredContent:

Nilai	Hasil yang terlihat model
`structured_first`	`structuredContent` Menggunakan saat ada, jika tidak`content`. Ini adalah nilai default.
`content_first`	Menggunakan nonempty `content`, jika tidak `structuredContent`.
`content_only`	`structuredContent`Mengabaikan .
`structured_only`	`content`Mengabaikan .
`both`	Menambahkan serial `structuredContent` setelah `content` blok.

Pilihan ini tidak mengubah payload Host yang dipertahankan. parse_tool_results mengambil alih kebijakan pemilihan.

Setiap transportasi MCP membatasi payload Host yang dipertahankan hingga 1 MiB secara default. Payload berukuran besar dihilangkan dari saluran Host, sementara hasil yang diurai masih mencapai model. Atur batas byte positif yang berbeda pada transportasi, atau gunakan None hanya saat Host hilir menerapkan batasnya sendiri:

mcp_server = MCPStreamableHTTPTool(
    name="Microsoft Learn MCP",
    url="https://learn.microsoft.com/api/mcp",
    max_host_payload_size_bytes=256 * 1024,
)

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 a `header_provider` that authenticates both connection-time and tool-call requests.

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 {api_key}"},
        ),
    ) as agent:
        query = "What tools are available to you?"
        print(f"User: {query}")
        result = await agent.run(query)
        print(f"Agent: {result.text}")

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

Jenis Alat MCP

Paket ini mcptool memungkinkan agen menggunakan alat dari server Model Context Protocol (MCP).

Menyambungkan ke server MCP

import (
    "github.com/microsoft/agent-framework-go/tool/mcptool"

    "github.com/modelcontextprotocol/go-sdk/mcp"
)

session, err := mcptool.Connect(ctx, &mcp.StreamableClientTransport{
    Endpoint: "https://learn.microsoft.com/api/mcp",
})
if err != nil {
    panic(err)
}
defer session.Close()

Mencantumkan dan menggunakan alat MCP

tools, err := mcptool.ListTools(ctx, session)
if err != nil {
    panic(err)
}

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Instructions: "You are a helpful assistant.",
    Config: agent.Config{
        Tools: tools,
    },
})

resp, err := a.RunText(ctx, "How to create an Azure storage account using az cli?").Collect()

Transportasi yang didukung

HTTP/SSE - mcp.StreamableClientTransport{Endpoint: "https://..."}
Stdio - Meluncurkan proses server MCP lokal

Tip

Lihat sampel alat MCP untuk contoh lengkap yang dapat dijalankan.

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

Warning

Instal paket NuGet yang diperlukan:

dotnet add package Microsoft.Agents.AI.Foundry --prerelease
dotnet add package Microsoft.Extensions.Hosting
dotnet add package ModelContextProtocol

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)

Bungkus agen dengan agenttool.New, daftarkan dengan server MCP menggunakan mcptool.AddTool, dan jalankan server melalui stdio:

import (
    "context"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
    "github.com/microsoft/agent-framework-go/tool/agenttool"
    "github.com/microsoft/agent-framework-go/tool/mcptool"
    "github.com/modelcontextprotocol/go-sdk/mcp"
)

jokeAgent := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Instructions: "You are good at telling jokes.",
    Config: agent.Config{
        Name:        "Joker",
        Description: "An agent that tells jokes.",
    },
})

server := mcp.NewServer(&mcp.Implementation{
    Name:    "agent-mcp-server",
    Version: "1.0.0",
}, nil)

mcptool.AddTool(server, agenttool.New(jokeAgent, agenttool.Config{}))

if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
    panic(err)
}

Tip

Lihat agen sebagai sampel alat MCP untuk contoh lengkap yang dapat dijalankan.

Langkah berikutnya

Percakapan & Memori

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-09-23

Menggunakan alat MCP dengan Agen

Pertimbangan untuk menggunakan server MCP pihak ketiga

Menyiapkan Klien MCP

Mengambil Alat yang Tersedia

Membuat Agen dengan Alat MCP

Menggunakan Agen

Konfigurasi Lingkungan

Manajemen Sumber Daya

Server MCP Umum

Jenis Alat MCP

MCPStdioTool - Server MCP Lokal

MCPStreamableHTTPTool - Server HTTP/SSE MCP

Pilih alat dengan nama yang tidak ambigu

Penghentian pengambilan sampel MCP

Mengontrol retensi payload Host

MCPWebsocketTool - Server MCP WebSocket

Server MCP Populer

Contoh lengkap

Jenis Alat MCP

Menyambungkan ke server MCP

Mencantumkan dan menggunakan alat MCP

Transportasi yang didukung

Mengekspos Agen sebagai Server MCP

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: