Menggunakan alat MCP yang dihosting dengan agen

Anda dapat memperluas kemampuan agen Microsoft Foundry Anda dengan menyambungkannya ke alat yang dihosting di server Protokol Konteks Model (MCP) jarak jauh (bawa titik akhir server MCP Anda sendiri).

Cara menggunakan alat Protokol Konteks Model

Bagian ini menjelaskan cara membuat agen dengan integrasi server Model Context Protocol (MCP) yang dihosting. Agen dapat menggunakan alat MCP yang dikelola dan dijalankan oleh layanan AI cadangan, memungkinkan akses yang aman dan terkontrol ke sumber daya eksternal.

Fitur Utama

  • Server MCP yang dihosting: Server MCP dihosting dan dikelola oleh Foundry, menghilangkan kebutuhan untuk mengelola infrastruktur server
  • Agen Persisten: Agen dibuat dan disimpan sisi server, memungkinkan percakapan stateful
  • Alur Kerja Persetujuan Alat: Mekanisme persetujuan yang dapat dikonfigurasi untuk pemanggilan alat MCP

Cara Kerjanya

1. Penyiapan Lingkungan

Sampel memerlukan dua variabel lingkungan:

  • AZURE_FOUNDRY_PROJECT_ENDPOINT: URL titik akhir proyek Foundry Anda
  • AZURE_FOUNDRY_PROJECT_MODEL_ID: Nama penyebaran model (default ke "gpt-4.1-mini")
var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
var model = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_MODEL_ID") ?? "gpt-4.1-mini";

2. Konfigurasi Agen

Agen dikonfigurasi dengan instruksi dan metadata tertentu:

const string AgentName = "MicrosoftLearnAgent";
const string AgentInstructions = "You answer questions by searching the Microsoft Learn content only.";

Ini membuat agen khusus untuk menjawab pertanyaan menggunakan dokumentasi Microsoft Learn.

3. Definisi Alat MCP

Sampel membuat definisi alat MCP yang menunjuk ke server MCP yang dihosting:

var mcpTool = new MCPToolDefinition(
    serverLabel: "microsoft_learn",
    serverUrl: "https://learn.microsoft.com/api/mcp");
mcpTool.AllowedTools.Add("microsoft_docs_search");

Komponen Utama:

  • serverLabel: Pengidentifikasi unik untuk instans server MCP
  • serverUrl: URL server MCP yang dihosting
  • AllowedTools: Menentukan alat mana dari server MCP yang dapat digunakan agen

4. Pembuatan Agen

Agen dibuat sisi server menggunakan Azure AI Projects SDK:

var aiProjectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());

var agentVersion = await aiProjectClient.AgentAdministrationClient.CreateAgentVersionAsync(
    AgentName,
    new ProjectsAgentVersionCreationOptions(
        new DeclarativeAgentDefinition(model)
        {
            Instructions = AgentInstructions,
            Tools = { mcpTool }
        }));

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.

Ini membuat agen versi yang:

  • Tinggal di layanan Foundry
  • Memiliki akses ke alat MCP yang ditentukan
  • Dapat mempertahankan status percakapan di beberapa interaksi

5. Pengambilan dan Eksekusi Agen

Agen yang dibuat diambil sebagai AIAgent instans:

AIAgent agent = aiProjectClient.AsAIAgent(agentVersion);

6. Konfigurasi Sumber Daya Alat

Sampel mengonfigurasi sumber daya alat dengan pengaturan persetujuan:

var runOptions = new ChatClientAgentRunOptions()
{
    ChatOptions = new()
    {
        RawRepresentationFactory = (_) => new ThreadAndRunOptions()
        {
            ToolResources = new MCPToolResource(serverLabel: "microsoft_learn")
            {
                RequireApproval = new MCPApproval("never"),
            }.ToToolResources()
        }
    }
};

Konfigurasi Kunci:

  • MCPToolResource: Menautkan instans server MCP ke eksekusi agen
  • RequireApproval: Kontrol saat persetujuan pengguna diperlukan untuk pemanggilan alat
    • "never": Alat dijalankan secara otomatis tanpa persetujuan
    • "always": Semua pemanggilan alat memerlukan persetujuan pengguna
    • Aturan persetujuan kustom juga dapat dikonfigurasi

7. Eksekusi Agen

Agen dipanggil dengan pertanyaan dan dijalankan menggunakan alat MCP yang dikonfigurasi:

AgentSession session = await agent.CreateSessionAsync();
var response = await agent.RunAsync(
    "Please summarize the Azure AI Agent documentation related to MCP Tool calling?",
    session,
    runOptions);
Console.WriteLine(response);

8. Pembersihan

Sampel menunjukkan pembersihan sumber daya yang tepat:

await aiProjectClient.AgentAdministrationClient.DeleteAgentAsync(agent.Id);

Tip

Lihat Sampel MCP yang Dihosting Agen .NET Foundry untuk contoh lengkap yang dapat dijalankan.

Foundry menyediakan integrasi yang mulus dengan server Model Context Protocol (MCP) melalui Python Agent Framework. Layanan ini mengelola hosting dan eksekusi server MCP, menghilangkan manajemen infrastruktur sambil menyediakan akses yang aman dan terkontrol ke alat eksternal.

Penyiapan Lingkungan

Konfigurasikan kredensial proyek Foundry Anda melalui variabel lingkungan:

import os
from azure.identity.aio import AzureCliCredential
from agent_framework.foundry import FoundryChatClient

# Required environment variables
os.environ["FOUNDRY_PROJECT_ENDPOINT"] = "https://<your-project>.services.ai.azure.com/api/projects/<project-id>"
os.environ["FOUNDRY_MODEL"] = "gpt-4o-mini"

Integrasi MCP Dasar

Buat agen Foundry dengan alat MCP yang dihosting:

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

async def basic_foundry_mcp_example():
    """Basic example of Foundry agent with hosted MCP tools."""
    async with AzureCliCredential() as credential:
        client = FoundryChatClient(credential=credential)
        # Create a hosted MCP tool using the client method
        learn_mcp = client.get_mcp_tool(
            name="Microsoft Learn MCP",
            url="https://learn.microsoft.com/api/mcp",
        )

        # Create agent with hosted MCP tool
        async with Agent(
            client=client,
            name="MicrosoftLearnAgent",
            instructions="You answer questions by searching Microsoft Learn content only.",
            tools=[learn_mcp],
        ) as agent:
            # Simple query without approval workflow
            result = await agent.run(
                "Please summarize the Azure AI Agent documentation related to MCP tool calling?"
            )
            print(result.text)

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

Konfigurasi MCP Multi-Alat

Gunakan beberapa alat MCP yang dihosting dengan satu agen:

async def multi_tool_mcp_example():
    """Example using multiple hosted MCP tools."""
    async with AzureCliCredential() as credential:
        client = FoundryChatClient(credential=credential)
        # Create multiple MCP tools using the client method
        learn_mcp = client.get_mcp_tool(
            name="Microsoft Learn MCP",
            url="https://learn.microsoft.com/api/mcp",
            approval_mode="never_require",  # Auto-approve documentation searches
        )
        github_mcp = client.get_mcp_tool(
            name="GitHub MCP",
            url="https://api.githubcopilot.com/mcp/",
            approval_mode="always_require",  # Require approval for GitHub operations
            headers={"Authorization": "Bearer github-token"},
        )

        # Create agent with multiple MCP tools
        async with Agent(
            client=client,
            name="MultiToolAgent",
            instructions="You can search documentation and access GitHub repositories.",
            tools=[learn_mcp, github_mcp],
        ) as agent:
            result = await agent.run(
                "Find Azure documentation and also check the latest commits in microsoft/semantic-kernel"
            )
            print(result.text)

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

Gunakan allowed_tools untuk mengontrol apakah layanan yang dihosting menerima filter alat MCP. Hilangkan argumen, atau teruskan None, untuk menghilangkan filter. Teruskan [] untuk mengirim daftar izin kosong eksplisit, atau berikan nama alat untuk hanya mengizinkan alat tersebut. Perbedaan ini berlaku untuk alat MCP yang dihosting yang dibuat oleh dan FoundryChatClientOpenAIChatClient.

Python Agent Framework menyediakan integrasi yang mulus dengan kemampuan MCP yang dihosting Foundry, memungkinkan akses yang aman dan dapat diskalakan ke alat eksternal sambil mempertahankan fleksibilitas dan kontrol yang diperlukan untuk aplikasi produksi.

Tip

Alat MCP juga dapat dibundel ke dalam konfigurasi Microsoft Foundry Toolbox — koleksi sisi server bernama versi alat yang dihosting. Lihat Microsoft Foundry Toolbox untuk lampiran agen terkelola dan panduan konsumsi MCP.

Contoh lengkap

# Copyright (c) Microsoft. All rights reserved.

import asyncio
import os

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
from dotenv import load_dotenv

"""
MCP GitHub Integration with Personal Access Token (PAT)

This example demonstrates how to connect to GitHub's remote MCP server using a Personal Access
Token (PAT) for authentication. The agent can use GitHub operations like searching repositories,
reading files, creating issues, and more depending on how you scope your token.

Prerequisites:
1. A GitHub Personal Access Token with appropriate scopes
   - Create one at: https://github.com/settings/tokens
   - For read-only operations, you can use more restrictive scopes
2. Environment variables:
   - GITHUB_PAT: Your GitHub Personal Access Token (required)
   - OPENAI_API_KEY: Your OpenAI API key (required)
   - OPENAI_MODEL: Your OpenAI model ID (required)
"""


async def github_mcp_example() -> None:
    """Example of using GitHub MCP server with PAT authentication."""
    # 1. Load environment variables from .env file if present
    load_dotenv()

    # 2. Get configuration from environment
    github_pat = os.getenv("GITHUB_PAT")
    if not github_pat:
        raise ValueError(
            "GITHUB_PAT environment variable must be set. Create a token at https://github.com/settings/tokens"
        )

    # 3. Create authentication headers with GitHub PAT
    auth_headers = {
        "Authorization": f"Bearer {github_pat}",
    }

    # 4. Create agent with the GitHub MCP tool using instance method
    # The MCP tool manages the connection to the MCP server and makes its tools available
    # Set approval_mode="never_require" to allow the MCP tool to execute without approval
    client = OpenAIChatClient()
    # This hosted MCP tool is executed remotely by OpenAI, not locally by your application.
    github_mcp_tool = client.get_mcp_tool(
        name="GitHub",
        url="https://api.githubcopilot.com/mcp/",
        headers=auth_headers,
        approval_mode="never_require",
    )

    # 5. Create agent with the GitHub MCP tool
    async with Agent(
        client=client,
        name="GitHubAgent",
        instructions=(
            "You are a helpful assistant that can help users interact with GitHub. "
            "You can search for repositories, read file contents, check issues, and more. "
            "Always be clear about what operations you're performing."
        ),
        tools=github_mcp_tool,
    ) as agent:
        # Example 1: Get authenticated user information
        query1 = "What is my GitHub username and tell me about my account?"
        print(f"\nUser: {query1}")
        result1 = await agent.run(query1)
        print(f"Agent: {result1.text}")

        # Example 2: List my repositories
        query2 = "List all the repositories I own on GitHub"
        print(f"\nUser: {query2}")
        result2 = await agent.run(query2)
        print(f"Agent: {result2.text}")


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

Alat MCP yang dihosting

Paket ini hostedtool menyediakan jenis penanda untuk alat yang dihosting. Alat-alat ini tidak dijalankan secara lokal - mereka menginformasikan layanan AI bahwa ia diizinkan untuk memanggil server MCP yang dikonfigurasi di sisi layanan. Di Go, gunakan alat MCP yang dihosting dengan OPENAI Responses API melalui openaiprovider.NewResponsesAgent.

Pengaturan lingkungan

Konfigurasikan model dan titik akhir server MCP melalui variabel lingkungan:

endpoint := os.Getenv("MCP_SERVER_URL")
if endpoint == "" {
    endpoint = "https://learn.microsoft.com/api/mcp"
}

deployment := os.Getenv("OPENAI_RESPONSES_MODEL")
if deployment == "" {
    deployment = "gpt-4o-mini"
}

Integrasi MCP dasar

import (
    "os"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/openaiprovider"
    "github.com/microsoft/agent-framework-go/tool"
    "github.com/microsoft/agent-framework-go/tool/hostedtool"
)

mcpTool := &hostedtool.MCPServer{
    ServerName:        "microsoft_learn",
    ServerDescription: "Search Microsoft Learn documentation.",
    ServerAddress:     endpoint,
    AllowedTools:      []string{"microsoft_docs_search"},
}

a := openaiprovider.NewResponsesAgent(client, openaiprovider.AgentConfig{
    Model:        deployment,
    Instructions: "You answer questions by searching Microsoft Learn content only.",
    Config: agent.Config{
        Name:  "MicrosoftLearnAgent",
        Tools: []tool.Tool{mcpTool},
    },
})

resp, err := a.RunText(ctx, "Summarize the Azure AI Agent documentation for MCP tool calling.").Collect()

Server MCP terautentikasi

Untuk server MCP yang memerlukan autentikasi, atur Authorization atau sediakan header. Muat rahasia dari penyimpanan atau lingkungan rahasia aplikasi Anda, dan hindari memeriksanya ke kontrol sumber.

githubMCPTool := &hostedtool.MCPServer{
    ServerName:    "github",
    ServerAddress: "https://api.githubcopilot.com/mcp/",
    Authorization: "Bearer " + os.Getenv("GITHUB_PAT"),
}

Beberapa server MCP

Berikan beberapa deklarasi server MCP yang dihosting ketika model harus dapat memilih antara set alat jarak jauh yang berbeda:

tools := []tool.Tool{
    &hostedtool.MCPServer{
        ServerName:    "microsoft_learn",
        ServerAddress: "https://learn.microsoft.com/api/mcp",
        AllowedTools:  []string{"microsoft_docs_search"},
    },
    &hostedtool.MCPServer{
        ServerName:    "github",
        ServerAddress: "https://api.githubcopilot.com/mcp/",
        Authorization: "Bearer " + os.Getenv("GITHUB_PAT"),
    },
}

a := openaiprovider.NewResponsesAgent(client, openaiprovider.AgentConfig{
    Model:        deployment,
    Instructions: "You can search Microsoft documentation and GitHub repositories.",
    Config: agent.Config{
        Name:  "MultiToolAgent",
        Tools: tools,
    },
})

Nota

Alat MCP yang dihosting memerlukan penyedia yang mendukungnya, seperti OpenAI Responses API melalui openaiprovider.NewResponsesAgent.

Langkah berikutnya

Alat MCP Lokal

  • Last updated on