Utilização de ferramentas MCP alojadas com agentes

Pode expandir as capacidades do seu agente Microsoft Foundry ligando-o a ferramentas alojadas em servidores remotos do Model Context Protocol (MCP) (traga o seu próprio endpoint de servidor MCP).

Como usar a ferramenta Model Context Protocol

Esta secção explica como criar um agente com uma integração de servidor com o Model Context Protocol (MCP) hospedado. O agente pode utilizar ferramentas MCP que são geridas e executadas pelo serviço de IA de apoio, permitindo acesso seguro e controlado a recursos externos.

Principais características

Servidor MCP Alojado: O servidor MCP é alojado e gerido pela Foundry, eliminando a necessidade de gerir a infraestrutura do servidor
Agentes persistentes: os agentes são criados e armazenados no lado do servidor, permitindo conversas com estado
Fluxo de trabalho de aprovação de ferramentas: mecanismos de aprovação configuráveis para invocações de ferramentas MCP

Como funciona

1. Configuração do ambiente

O exemplo requer duas variáveis de ambiente:

AZURE_FOUNDRY_PROJECT_ENDPOINT: URL do endpoint do seu projeto Foundry
AZURE_FOUNDRY_PROJECT_MODEL_ID: O nome da implantação do modelo (o padrão é "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. Configuração do agente

O agente é configurado com instruções e metadados específicos:

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

Isso cria um agente especializado para responder a perguntas usando a documentação do Microsoft Learn.

3. Definição da ferramenta MCP

O exemplo cria uma definição de ferramenta MCP que aponta para um servidor MCP hospedado:

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

Componentes-chave:

serverLabel: Um identificador exclusivo para a instância do servidor MCP
serverUrl: A URL do servidor MCP hospedado
AllowedTools: Especifica quais ferramentas do servidor MCP o agente pode usar

4. Criação de Agentes

O agente é criado do lado do servidor usando o 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 }
        }));

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.

Isto cria um agente versionado que:

Vive no serviço da fundição
Tem acesso às ferramentas MCP especificadas
Pode manter o estado da conversação em várias interações

5. Recuperação e Execução do Agente

O agente criado é recuperado como uma AIAgent instância:

AIAgent agent = aiProjectClient.AsAIAgent(agentVersion);

6. Configuração de recursos da ferramenta

O exemplo configura recursos da ferramenta com configurações de aprovação:

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

Configuração da chave:

MCPToolResource: Vincula a instância do servidor MCP à execução do agente
RequireApproval: Controla quando a aprovação do usuário é necessária para invocações de ferramentas
- "never": As ferramentas são executadas automaticamente sem aprovação
- "always": Todas as invocações de ferramentas requerem aprovação do usuário
- Regras de aprovação personalizadas também podem ser configuradas

7. Execução do agente

O agente é invocado com uma pergunta e é executado usando as ferramentas MCP configuradas:

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

O exemplo demonstra a limpeza adequada de recursos:

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

Sugestão

Consulte o exemplo MCP hospedado por agente do .NET Foundry para um exemplo completo e executável.

O Foundry proporciona integração perfeita com servidores Model Context Protocol (MCP) através do Python Agent Framework. O serviço gerencia a hospedagem e execução do servidor MCP, eliminando o gerenciamento de infraestrutura e fornecendo acesso seguro e controlado a ferramentas externas.

Configuração do ambiente

Configure as credenciais do seu projeto Foundry através de variáveis de ambiente:

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"

Integração MCP básica

Crie um agente Foundry com ferramentas MCP alojadas:

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

Configuração MCP Multi-Tool

Use várias ferramentas MCP hospedadas com um único agente:

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

O Python Agent Framework proporciona uma integração perfeita com as capacidades MCP alojadas do Foundry, permitindo acesso seguro e escalável a ferramentas externas, mantendo a flexibilidade e controlo necessários para aplicações de produção.

Sugestão

As ferramentas MCP também podem ser agrupadas nas caixas de ferramentas Foundry — coleções nomeadas e versionadas do lado do servidor de configurações alojadas de ferramentas. As caixas de ferramentas permitem gerir a configuração da ferramenta uma vez e reutilizá-la entre agentes. Consulte a secção Toolboxes na página do fornecedor Microsoft Foundry para detalhes sobre a busca de caixas de ferramentas e o percurso de consumo do MCP.

Exemplo completo

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

Ferramentas MCP alojadas

O hostedtool pacote fornece tipos de marcadores para ferramentas alojadas. Estas ferramentas não são executadas localmente — informam o serviço de IA de que pode chamar o servidor MCP configurado do lado do serviço. No Go, utilize ferramentas MCP alojadas com a API OpenAI Responses através de openaiprovider.NewResponsesAgent.

Configuração do ambiente

Configure o modelo e o endpoint do servidor MCP através de variáveis de ambiente:

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

Integração básica do MCP

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

Servidores MCP autenticados

Para servidores MCP que requerem autenticação, defina Authorization ou forneça cabeçalhos. Carregue segredos do armazenamento ou ambiente secreto da sua aplicação e evite que sejam registados no controlo de versão.

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

Múltiplos servidores MCP

Fornecer múltiplas declarações de servidores MCP alojados quando o modelo deve poder escolher entre diferentes conjuntos de ferramentas remotas:

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,
    },
})

Note

As ferramentas MCP alojadas requerem um fornecedor que as suporte, como a API OpenAI Responses através de openaiprovider.NewResponsesAgent.

Próximos passos

Ferramentas MCP Locais

Comentários

Esta página foi útil?

Last updated on 2026-07-10

Utilização de ferramentas MCP alojadas com agentes

Como usar a ferramenta Model Context Protocol

Principais características

Como funciona

1. Configuração do ambiente

2. Configuração do agente

3. Definição da ferramenta MCP

4. Criação de Agentes

5. Recuperação e Execução do Agente

6. Configuração de recursos da ferramenta

7. Execução do agente

8. Limpeza

Configuração do ambiente

Integração MCP básica

Configuração MCP Multi-Tool

Exemplo completo

Ferramentas MCP alojadas

Configuração do ambiente

Integração básica do MCP

Servidores MCP autenticados

Múltiplos servidores MCP

Próximos passos

Comentários

Recursos adicionais