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). Permite a integração consistente e escalável de ferramentas externas nos fluxos de trabalho dos modelos.

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-lhe passar cabeçalhos personalizados, como chaves ou esquemas de autenticação, que um servidor MCP remoto possa precisar. Recomendamos que reveja todos os dados partilhados com servidores MCP remotos e que registe esses dados para efeitos de auditoria. Esteja ciente das práticas que não são da Microsoft para retenção e localização de dados.

Importante

Pode especificar cabeçalhos por execução incluindo-os nos recursos da ferramenta em cada execução, ou configurar ferramentas header_provider MCP locais em Python. Revise quaisquer chaves API, tokens de acesso OAuth ou outras credenciais partilhadas com servidores MCP remotos.

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

• Práticas recomendadas de segurança no site do Model Context Protocol.
• Compreendendo e mitigando riscos de segurança em implementações MCP no Blog da Comunidade de Segurança da Microsoft.

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:

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

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:

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

Tip

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/02-agents/ModelContextProtocol/Agent_MCP_Server.

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

Observação

Em instalações mínimas de Python, o suporte ao MCP pode ter de ser instalado manualmente. Instale mcp --pre para usar MCPStdioTool, MCPStreamableHTTPTool, ou Agent.as_mcp_server(). Instala mcp[ws] --pre se também precisares MCPWebsocketToolde .

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

O cliente HTTP que MCPStreamableHTTPTool cria não persiste cookies de resposta. Se o servidor precisar de cookies para autenticação, sessões ou afinidade com balanceador de carga, passe uma configuração httpx.AsyncClient por http_client=. O cliente fornecido mantém o seu comportamento de cookies e permanece como propriedade do chamador. Defina um cliente com cookies e a sua sessão de ferramenta MCP para um principal autenticado.

Para endpoints HTTP autenticados, use static_headers para credenciais fixas ou header_provider para valores derivados de cada execução. Ambos os caminhos adicionam cabeçalhos apenas a pedidos para a origem configurada e removem-nos dos redirecionamentos cruzados de origem. Cabeçalhos fixos são copiados quando a ferramenta é criada e não serializam chamadas concorrentes. Quando ambas as opções fornecem o mesmo cabeçalho, o valor dinâmico de header_provider tem prioridade.

Durante as chamadas de ferramenta geradas, header_provider recebe apenas o host function_invocation_kwargsda execução. Não recebe argumentos de ferramenta fornecidos pelo modelo, mesmo quando um argumento de modelo tem o mesmo nome. Uma chamada direta call_tool(...) transmite os argumentos das palavras-chave fornecidas pelo chamador ao fornecedor. Os valores do modelo ainda podem ter precedência nos argumentos das ferramentas de saída separadamente fundidas, mas não controlam os cabeçalhos de autenticação.

Os cabeçalhos fixos e dinâmicos formam juntos a identidade efetiva da sessão HTTP. Os nomes dos cabeçalhos são comparados de forma insensível a maiúsculas minúsculas, enquanto os valores permanecem a diferença de maiúsculas. Argumentos de palavras-chave em tempo de execução também são elegíveis para argumentos de ferramentas de saída quando o esquema do servidor permite o mesmo nome. Para manter as credenciais fora dos argumentos das ferramentas, capture-as no fornecedor através de um fecho ou ContextVar, use static_headers, ou forneça um cliente HTTP personalizado.

As sessões detidas pelo framework associam esta identidade eficaz quando se ligam. Se uma execução posterior produzir uma identidade diferente, a ferramenta reconecta-se antes de enviar a chamada e atualiza a descoberta da ferramenta e do prompt derivada da sessão. Inicializar, descobrir, ping em segundo plano e outros pedidos de vida útil da ligação continuam a usar os cabeçalhos vinculados a essa sessão.

As sessões fornecidas pelo ouvinte continuam a ser propriedade do ouvinte. Como o wrapper não consegue estabelecer ou reconectar uma identidade desconhecida para essas sessões, a resolução dinâmica do cabeçalho com uma identidade desconhecida é rejeitada. Uma identidade alterada também é rejeitada; use uma instância de ferramenta gerida por framework separada.

Se a ferramenta se ligar com entusiasmo antes de uma execução, o fornecedor recebe um mapeamento vazio para pedidos de ligação ao longo da vida. Recolha ou atualize uma credencial de construção no prestador deste caso. Se uma credencial só chegar em tempo de execução, passe a ferramenta run(tools=[...]) não ligada para function_invocation_kwargs que a execução estabeleça a ligação.

A KeyError do fornecedor é tolerado apenas quando nenhuma execução iniciou a ligação, e o pedido continua sem cabeçalhos de fornecedor. Após uma execução seed da ligação, uma chave em falta é um erro de configuração e a exceção é apresentada.

Selecione ferramentas por nome inequívoco

Quando definir allowed_tools ou listar ferramentas em approval_mode, use o nome bruto da ferramenta remota ou um nome com prefixo inequívoco. Se um nome configurado corresponder a múltiplos nomes remotos brutos após normalização, o Agent Framework levanta ToolExecutionException. Use um nome bruto exato ou uma alteração tool_name_prefix para tornar os nomes locais únicos.

Depreciação da amostragem MCP

Warning

A amostragem MCP iniciada pelo servidor está sampling_callback obsoleta a partir da especificação MCP versão 2026-07-28 e é removida até, no máximo, 2027-07-28. Não crie novas integrações com esta funcionalidade. Os servidores MCP devem contactar diretamente as APIs dos fornecedores modelo.

Retenção da carga útil do Host de Controlo

Quando um transporte Host, como o AG-UI, consome um resultado de ferramenta MCP, o Agent Framework mantém o resultado completo seguro em JSON separadamente do valor frontal do modelo analisado. Isto permite que o Host receba campos, por exemplo structuredContent , sem adicionar dados apenas do Host ao histórico do modelo.

Use tool_result_content em qualquer transporte MCP para selecionar o valor visível no modelo quando um resultado contém tanto content e structuredContent:

Value	Resultado visível no modelo
structured_first	Utiliza-se structuredContent quando presente, caso contrário content. Esse valor é o padrão.
content_first	Usa não vazio content, caso contrário structuredContent.
content_only	Ignora structuredContent.
structured_only	Ignora content.
both	Acrescenta em série structuredContent após os content blocos.

Esta seleção não altera a carga útil do Host retida. parse_tool_results sobrepõe-se à política de seleção.

Cada transporte MCP limita por defeito uma carga útil do Host retida a 1 MiB. Cargas úteis sobredimensionadas são omitidas do canal Host, enquanto o resultado analisado ainda chega ao modelo. Defina um limite positivo diferente de bytes no transporte, ou use None apenas quando o Host a jusante aplica o seu próprio limite:

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

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

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

Tipos de ferramentas MCP

O mcptool pacote permite aos agentes usar ferramentas de servidores Model Context Protocol (MCP).

Conectar-se a um servidor 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()

Liste e utilize ferramentas 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()

Transportes suportados

• HTTP/SSE - mcp.StreamableClientTransport{Endpoint: "https://..."}
• Stdio - Iniciar um processo servidor MCP local

Tip

Veja o exemplo de ferramentas MCP para um exemplo completo e executável.

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

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.

Instale os pacotes NuGet necessários:

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

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

Observação

Python agent.as_mcp_server() também depende do pacote opcional mcp . Se usares uma instalação slim/baseada em core, lança pip install mcp --pre primeiro.

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

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)

Envolve o agente com agenttool.New, regista-o num servidor MCP usando mcptool.AddTool, e executa o servidor sobre 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

Veja o agente como exemplo de ferramenta MCP para um exemplo completo e executável.

Passos seguintes

Conversas & Memória