Partilhar via

Usando ferramentas MCP com agentes

O Model Context Protocol é um padrão aberto que define como os aplicativos fornecem ferramentas e dados contextuais para grandes modelos de linguagem (LLMs). Ele permite a integração consistente e escalável de ferramentas externas em fluxos de trabalho de modelo.

O Microsoft Agent Framework suporta integração com servidores Model Context Protocol (MCP), permitindo que os seus agentes acedam a ferramentas e serviços externos. Este guia mostra como se conectar a um servidor MCP e usar suas ferramentas dentro do seu agente.

Considerações para a utilização de servidores MCP de terceiros

A sua utilização de servidores Model Context Protocol está sujeita aos termos entre si e o fornecedor do serviço. Quando você se conecta a um serviço que não é da Microsoft, alguns dos seus dados (como conteúdo de prompt) são passados para o serviço que não é da Microsoft ou seu aplicativo pode receber dados do serviço que não é da Microsoft. O Cliente é responsável pela sua utilização de serviços e dados que não sejam da Microsoft, juntamente com quaisquer encargos associados a essa utilização.

Os servidores MCP remotos que você decide usar com a ferramenta MCP descrita neste artigo foram criados por terceiros, não pela Microsoft. A Microsoft não testou nem verificou esses servidores. A Microsoft não tem qualquer responsabilidade perante si ou terceiros em relação à sua utilização de quaisquer servidores MCP remotos.

Recomendamos que você analise e acompanhe cuidadosamente quais servidores MCP você adiciona aos seus aplicativos baseados no Agent Framework. Também recomendamos que você confie em servidores hospedados pelos próprios provedores de serviços confiáveis em vez de proxies.

A ferramenta MCP permite que você passe cabeçalhos personalizados, como chaves de autenticação ou esquemas, que um servidor MCP remoto pode precisar. Recomendamos que você revise todos os dados compartilhados com servidores MCP remotos e registre os dados para fins de auditoria. Esteja ciente das práticas que não são da Microsoft para retenção e localização de dados.

Importante

Só pode especificar cabeçalhos incluindo-os em tool_resources em cada execução. Dessa forma, você pode colocar chaves de API, tokens de acesso OAuth ou outras credenciais diretamente em sua solicitação. Os cabeçalhos que são passados estão disponíveis apenas para a execução atual e não são persistentes.

Para mais informações sobre a segurança do MCP, consulte:

A versão .NET do Agent Framework pode ser usada em conjunto com o SDK oficial do MCP C# para permitir que o seu agente chame ferramentas MCP.

O exemplo a seguir mostra como:

  1. Configurar e servidor MCP
  2. Recuperar a lista de ferramentas disponíveis do Servidor MCP
  3. Converter as ferramentas MCP em AIFunction's para que possam ser adicionadas a um agente
  4. Invoque as ferramentas de um agente usando a chamada de função

Configurando um cliente MCP

Primeiro, crie um cliente MCP que se conecte ao servidor MCP desejado:

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

Neste exemplo:

  • Nome: Um nome amigável para sua conexão de servidor MCP
  • Comando: O executável para executar o servidor MCP (aqui usando npx para executar um pacote Node.js)
  • Argumentos: argumentos de linha de comando passados para o servidor MCP

Recuperando ferramentas disponíveis

Uma vez conectado, recupere a lista de ferramentas disponíveis no servidor MCP:

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

O ListToolsAsync() método retorna uma coleção de ferramentas que o servidor MCP expõe. Essas ferramentas são convertidas automaticamente em objetos AITool que podem ser usados pelo seu agente.

Crie um Agente com Ferramentas MCP

Crie seu agente e forneça as ferramentas MCP durante a inicialização:

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

Advertência

DefaultAzureCredential é conveniente para o desenvolvimento, mas requer uma consideração cuidadosa na produção. Em produção, considere usar uma credencial específica (por exemplo, ManagedIdentityCredential) para evitar problemas de latência, sondagens não intencionais de credenciais e potenciais riscos de segurança provenientes de mecanismos de recurso.

Pontos principais:

  • Instruções: Forneça instruções claras que se alinham com os recursos de suas ferramentas MCP
  • Ferramentas: Converta as ferramentas MCP em AITool objetos e espalhe-as na matriz de ferramentas
  • O agente terá automaticamente acesso a todas as ferramentas fornecidas pelo servidor MCP

Usando o agente

Uma vez configurado, seu agente pode usar automaticamente as ferramentas MCP para atender às solicitações do usuário:

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

O agente irá:

  1. Analise a solicitação do usuário
  2. Determinar quais ferramentas MCP são necessárias
  3. Chame as ferramentas apropriadas através do servidor MCP
  4. Sintetizar os resultados numa resposta coerente

Configuração do ambiente

Certifique-se de configurar as variáveis de ambiente necessárias:

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

Gestão de Recursos

Descarte sempre corretamente os recursos do cliente MCP:

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

O uso await using garante que a conexão do cliente MCP seja fechada corretamente quando sair do escopo.

Servidores MCP comuns

Os servidores MCP populares incluem:

  • @modelcontextprotocol/server-github: Acesse repositórios e dados do GitHub
  • @modelcontextprotocol/server-filesystem: Operações do sistema de arquivos
  • @modelcontextprotocol/server-sqlite: Acesso ao banco de dados SQLite

Cada servidor fornece diferentes ferramentas e recursos que estendem a funcionalidade do seu agente. Essa integração permite que seus agentes acessem perfeitamente dados e serviços externos, mantendo os benefícios de segurança e padronização do Model Context Protocol.

O código-fonte completo e as instruções para executar este exemplo estão disponíveis em https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server.

Sugestão

Consulte os exemplos do .NET para exemplos completos executáveis.

Isso permite que seus agentes acessem ferramentas e serviços externos sem problemas.

Tipos de ferramentas MCP

O Agent Framework suporta três tipos de conexões MCP:

MCPStdioTool - Servidores MCP Locais

Use MCPStdioTool para se conectar a servidores MCP que são executados como processos locais usando entrada/saída padrão:

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

Use MCPStreamableHTTPTool para se conectar a servidores MCP via HTTP com Server-Sent Eventos:

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 - Servidores WebSocket MCP

Use MCPWebsocketTool para se conectar a servidores MCP através de conexões 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(
            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())

Servidores MCP comuns que você pode usar com o Python Agent Framework:

  • Calculadora: uvx mcp-server-calculator - Cálculos matemáticos
  • Sistema de arquivos: uvx mcp-server-filesystem - Operações do sistema de arquivos
  • GitHub: npx @modelcontextprotocol/server-github - Acesso ao repositório GitHub
  • SQLite: uvx mcp-server-sqlite - Operações de banco de dados

Cada servidor fornece diferentes ferramentas e recursos que estendem a funcionalidade do seu agente, mantendo os benefícios de segurança e padronização do Protocolo de Contexto do Modelo.

Exemplo completo

# 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}")

Expor um Agente como Servidor MCP

Pode expor um agente como servidor MCP, permitindo que seja usado como ferramenta por qualquer cliente compatível com MCP (como VS Code, GitHub Copilot Agents ou outros agentes). O nome e a descrição do agente tornam-se os metadados do servidor MCP.

Envolva o agente numa ferramenta de função usando .AsAIFunction(), crie um McpServerTool, e registe-o num servidor MCP:

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

Instale os pacotes NuGet necessários:

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

Peça .as_mcp_server() a um agente para o expor como servidor MCP:

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

Configure o servidor MCP para ouvir sobre entrada/saída padrão:

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)

Próximos passos

Usando fluxos de trabalho como agentes

  • Last updated on