Como Construir Servidores MCP com o SDK de Agentes OpenAI

O SDK de Agentes da OpenAI agora suporta MCP (Protocolo de Contexto do Modelo), uma mudança de jogo para a interoperabilidade de IA. Isso permite que os desenvolvedores conectem modelos de IA a ferramentas e fontes de dados externas de forma eficiente. Neste guia técnico, vamos orientá-lo na construção de Servidores MCP com o SDK de Agentes da OpenAI para aprimorar suas aplicações de IA.

💡

Quer otimizar o desenvolvimento da sua API? Experimente Apidog—uma ferramenta poderosa para projetar, testar e gerenciar APIs, perfeita para acelerar seu ciclo de desenvolvimento de API.

botão

O que são Servidores MCP e por que usá-los com o SDK de Agentes da OpenAI?

MCP (Protocolo de Contexto do Modelo) é um protocolo aberto que padroniza como as aplicações fornecem contexto para grandes modelos de linguagem (LLMs). Pense no MCP como uma porta USB-C para aplicações de IA - ele atua como um conector universal que permite que modelos de IA interajam com diferentes fontes de dados e ferramentas de forma integrada.

O SDK de Agentes da OpenAI integra Servidores MCP para permitir que os agentes acessem ferramentas e dados externos. O uso de Servidores MCP garante uma interação suave entre seu agente de IA e os recursos remotos e locais. Essa integração reduz a complexidade na chamada de ferramentas e melhora a funcionalidade do agente.

Aqui estão alguns exemplos que você pode construir com combinações de OpenAI + Servidor MCP:

🕵️‍♂️ used gitingest to download all the docs from @OpenAIDevs Agents SDK

excellent for providing to your AI Coding Agent as context if building with the OpenAI Agents SDK

download from the GitHub link below ⬇️ pic.twitter.com/0szZ43wMTv
— Dan Mac (@daniel_mac8) 23 de março de 2025

Passos para Usar a Integração MCP da OpenAI

Requisitos para Construir Servidores MCP com o SDK de Agentes da OpenAI

Antes de começar, certifique-se de que você possui:

Python 3.8 ou superior instalado em seu sistema
SDK de Agentes da OpenAI instalado via pip: pip install openai-agents
Node.js configurado para executar comandos do servidor MCP como npx para certos exemplos
Um diretório de projeto com ambiente virtual inicializado para gerenciamento de dependências
Compreensão básica de programação assíncrona em Python, já que o SDK utiliza async/await

Passo 1: Configure seu Ambiente de Desenvolvimento para Servidores MCP

# Crie um novo diretório para seu projeto
mkdir mcp-agent-project && cd mcp-agent-project

# Inicialize um ambiente virtual Python
python -m venv venv && source venv/bin/activate

# Instale as dependências necessárias
pip install openai-agents pyyaml

Crie um arquivo de configuração chamado mcp_agent.config.yaml para definir os Servidores MCP. Esta configuração aponta para um servidor MCP no sistema de arquivos para acessar arquivos locais.

Passo 2: Entenda os Tipos de Servidores MCP no SDK de Agentes da OpenAI

Os Servidores MCP vêm em dois tipos, conforme definido na especificação MCP:

servidores stdio: Executam localmente como um subprocesso da sua aplicação
servidores HTTP sobre SSE: Operam remotamente e se conectam via URL

O SDK de Agentes da OpenAI fornece duas classes para lidar com esses servidores:

MCPServerStdio: Para servidores locais baseados em subprocesso
MCPServerSse: Para servidores HTTP sobre SSE remotos

Escolha o tipo de servidor com base na arquitetura da sua aplicação e nos requisitos de latência. Servidores stdio são ideais para desenvolvimento local, enquanto servidores SSE são mais adequados para sistemas distribuídos.

Passo 3: Conecte um Servidor MCP ao Seu Agente da OpenAI

Importe as classes necessárias do SDK de Agentes da OpenAI e defina seu servidor MCP:

from openai_agents import Agent, MCPServerStdio

# Defina o caminho para seus arquivos de exemplo
samples_dir = "/caminho/para/seus/arquivos"

# Use o gerenciador de contexto assíncrono para inicializar o servidor
async with MCPServerStdio(
    params={
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
    }
) as server:
    # Liste as ferramentas fornecidas pelo servidor MCP
    tools = await server.list_tools()

    # Crie um agente que usa o servidor MCP
    agent = Agent(
        name="Assistente",
        instructions="Use as ferramentas do sistema de arquivos para ajudar o usuário com suas tarefas.",
        mcp_servers=[server]
    )

    # Execute o agente
    result = await agent.run("Liste os arquivos no diretório.")

Essa configuração permite que o agente utilize ferramentas de sistema de arquivos dinamicamente durante a execução.

Passo 4: Otimize o Desempenho com Cache de Ferramentas

Os Servidores MCP chamam list_tools() toda vez que um agente é executado, o que pode introduzir latência, especialmente com servidores remotos. Para reduzir essa sobrecarga, você pode ativar o cache de ferramentas:

# Ative o cache ao inicializar o servidor
async with MCPServerStdio(
    params={
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
    },
    cache_tools_list=True  # Ative o cache
) as server:
    # A lista de ferramentas será armazenada em cache após a primeira chamada
    tools = await server.list_tools()

Considerações importantes para o cache:

Use o cache apenas se tiver certeza de que a lista de ferramentas não mudará durante a execução
Se as ferramentas precisarem ser atualizadas, invalide o cache: await server.invalidate_tools_cache()
O cache funciona tanto para servidores stdio quanto SSE, com maiores benefícios de desempenho para servidores remotos

Passo 5: Implemente a Integração do Servidor MCP com o Fluxo de Trabalho do Seu Agente

Para integrar completamente os servidores MCP com seu agente:

from openai_agents import Agent, MCPServerStdio, MCPServerSse

async def run_agent_with_mcp_servers():
    # Inicialize o servidor MCP stdio local
    local_server = MCPServerStdio(
        params={
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "./arquivos_locais"],
        },
        cache_tools_list=True
    )

    # Inicialize o servidor MCP SSE remoto (se necessário)
    remote_server = MCPServerSse(
        url="<https://seu-servidor-mcp-remoto.com/stream>",
        cache_tools_list=True
    )

    async with local_server, remote_server:
        # Crie um agente com ambos os servidores
        agent = Agent(
            name="AgenteMultiFerramentas",
            instructions="Use as ferramentas disponíveis para realizar tarefas.",
            mcp_servers=[local_server, remote_server]
        )

        # Execute o agente
        result = await agent.run("Complete a tarefa solicitada usando ferramentas apropriadas.")
        return result

Essa abordagem dá ao seu agente acesso a ferramentas locais e remotas através de interfaces MCP padronizadas.

Passo 6: Depure e Monitore Seus Servidores MCP

Estratégias eficazes de depuração e monitoramento incluem:

Verificar os logs do servidor MCP para erros durante a execução das ferramentas
Usar o painel de rastreamento do SDK de Agentes da OpenAI para monitorar chamadas de ferramentas
Testar casos extremos, como nomes de ferramentas inválidos ou indisponibilidade do servidor, para garantir robustez
Monitorar latência ao usar servidores SSE remotos e otimizar com cache, se necessário
Aproveitar a funcionalidade de rastreamento integrada do SDK, que captura automaticamente:

Chamadas aos servidores MCP para listar ferramentas
Informações relacionadas ao MCP em chamadas de funções

Além disso, você também deve considerar usar uma ferramenta de Teste de API Tudo-em-Um para facilitar seu ciclo de Desenvolvimento de API.

Apidog é uma ferramenta poderosa que simplifica o desenvolvimento de APIs, tornando-se um excelente aliado ao construir Servidores MCP com o SDK de Agentes da OpenAI. Como os Servidores MCP muitas vezes envolvem interação com APIs—seja para servidores remotos HTTP sobre SSE ou para testar chamadas de ferramentas—o Apidog pode melhorar seu fluxo de trabalho.

botão

Conclusão

Construir Servidores MCP com o SDK de Agentes da OpenAI abre novas possibilidades para aprimorar agentes de IA com ferramentas e fontes de dados externas. A interface MCP padronizada torna a integração mais simples e confiável em diferentes ambientes.

Ao seguir este guia, você pode criar agentes poderosos que aproveitam tanto recursos locais quanto remotos por meio do Protocolo de Contexto do Modelo. À medida que o ecossistema MCP continua a crescer, seus agentes poderão acessar um conjunto cada vez mais amplo de ferramentas e capacidades.

Para mais exemplos e documentação detalhada, visite a documentação oficial do MCP do SDK de Agentes da OpenAI. O suporte do SDK ao MCP representa um grande avanço para tornar agentes de IA mais capazes e conectados ao mundo digital.

botão