Ir para o conteúdo principal
Português— Escolher um idioma
Menu

MCP e Conectores: Ligar Serviços Externos

Aula 9 de 25 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. MCP e Conectores: Ligar Serviços Externos
  2. O que é o MCP?
  3. Ligar um Servidor MCP
  4. Servidores MCP Remotos via SSE
  5. Conectores da OpenAI
  6. Combinar MCP e Ferramentas de Função
  7. Filtrar Ferramentas MCP
  8. Gerir Erros do MCP
  9. Pontos-chave

Atualizado a 2 de novembro de 2026 — Agent Builder. A 3 de junho de 2026, a OpenAI anunciou o encerramento do Agent Builder, agendado para 30 de novembro de 2026; o ChatKit permanece disponível. Doravante, a OpenAI direciona os utilizadores para o Agents SDK ou para os agentes do espaço de trabalho do ChatGPT. Desde 10 de setembro de 2026, a OpenAI disponibiliza uma API de Agentes em beta público que aloja a orquestração de agentes (ver ChatGPT em 2026, Lição 10).

MCP e Conectores: Ligar Serviços Externos

O Model Context Protocol (MCP) é um padrão aberto que permite ao seu agente ligar-se a serviços externos de forma normalizada. Em vez de reescrever integrações para cada serviço, basta ligar um servidor MCP e o seu agente ganha instantaneamente novas ferramentas. Onde antes escreveria trezentas linhas de código cliente para o GitHub, agora precisa apenas de uma única declaração de servidor.

O que é o MCP?

O MCP é um padrão aberto que define como um cliente — o seu agente — comunica com um servidor, ou seja, um serviço externo. Cada servidor MCP expõe ferramentas que o seu agente pode utilizar. O protocolo gere o transporte, a serialização e a descoberta de ferramentas. Esta última funcionalidade é a mais valiosa para o trabalho diário: o agente consulta o servidor para saber o que este pode fazer, pelo que não precisa de manter uma lista manualmente. O Agents SDK inclui suporte nativo para MCP e liga-se a qualquer servidor compatível.

Ligar um Servidor MCP

O SDK fornece a classe MCPServerStdio para servidores locais que comunicam via stdin/stdout — tipicamente um processo Node iniciado com npx.

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

# Servidor MCP local (comunica via stdin/stdout)
file_server = MCPServerStdio(
    name="File Manager",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "/path/to/folder"],
)

async def main():
    async with file_server:
        agent = Agent(
            name="File Agent",
            instructions="You manage files for the user.",
            mcp_servers=[file_server],
        )
        result = await Runner.run(agent, "List the files in the root folder.")
        print(result.final_output)

O bloco async with não é apenas decorativo: inicia o processo do servidor, descobre as suas ferramentas e encerra-o corretamente quando o bloco termina. Um agente criado fora deste contexto não terá quaisquer ferramentas.

Servidores MCP Remotos via SSE

Para servidores alojados, utilize MCPServerSse e o transporte SSE (Server-Sent Events). A lógica mantém-se; apenas o URL e os cabeçalhos de autenticação mudam.

from agents.mcp import MCPServerSse

github_server = MCPServerSse(
    name="GitHub",
    url="https://mcp.github.com/sse",
    headers={"Authorization": "Bearer ghp_your_token"},
)

async def main():
    async with github_server:
        agent = Agent(
            name="DevOps Agent",
            instructions="You manage GitHub repositories.",
            mcp_servers=[github_server],
        )
        result = await Runner.run(
            agent,
            "Create an issue in the my-project repo with the title 'Critical Bug'"
        )
        print(result.final_output)

Conectores da OpenAI

Além do MCP, a OpenAI oferece conectores geridos diretamente na plataforma. Estes integram-se no Agent Builder e permanecem utilizáveis via SDK sem que precise de alojar um servidor.

from agents import Agent, Runner

# Os conectores configurados no Agent Builder estão automaticamente disponíveis
agent = Agent(
    name="CRM Agent",
    instructions="""You are a CRM assistant. Use the connectors
    to access Salesforce, HubSpot, and Google Workspace.""",
    model="gpt-5.6-terra",
    # Os conectores estão ligados à configuração do agente na plataforma
)

A ausência do parâmetro mcp_servers faz sentido: os conectores estão vinculados à configuração do agente na plataforma. Estes tratam por si da autenticação OAuth, da paginação e da limitação de taxa — três áreas que consomem tempo significativo quando geridas manualmente.

Combinar MCP e Ferramentas de Função

Não precisa de escolher. Um único agente pode utilizar um servidor MCP para acesso a dados e as suas próprias funções para lógica de negócio que não queira delegar.

from agents import Agent, Runner, function_tool
from agents.mcp import MCPServerStdio

@function_tool
def calculate_invoice(amount_excl_tax: float, vat_rate: float = 20.0) -> str:
    """Calculates the total amount including tax for an invoice."""
    amount_incl_tax = amount_excl_tax * (1 + vat_rate / 100)
    return f"Excl. tax: €{amount_excl_tax}, VAT {vat_rate}%: €{amount_excl_tax * vat_rate / 100:.2f}, Incl. tax: €{amount_incl_tax:.2f}"

db_server = MCPServerStdio(
    name="Database",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost/mydb"],
)

async def main():
    async with db_server:
        agent = Agent(
            name="Accounting Agent",
            instructions="""You handle accounting.
            Use the database for customer data
            and the calculation function for invoices.""",
            tools=[calculate_invoice],
            mcp_servers=[db_server],
        )
        result = await Runner.run(
            agent,
            "Retrieve orders for customer Alice and calculate the total invoice"
        )
        print(result.final_output)

O cálculo do IVA permanece no seu código, onde é testável e auditável; a recuperação de encomendas passa pelo servidor MCP PostgreSQL. É esta separação que deve procurar alcançar.

Filtrar Ferramentas MCP

Um servidor MCP pode expor dezenas de ferramentas, a maioria das quais não será relevante para o seu caso de uso — e cada uma consome contexto e aumenta o risco de uma chamada inadequada. Comece por inspecionar o que está realmente disponível.

server = MCPServerStdio(
    name="GitHub",
    command="npx",
    args=["-y", "@modelcontextprotocol/server-github"],
)

# Pode filtrar durante a ligação
async with server:
    tools = await server.list_tools()
    # Inspecionar ferramentas disponíveis
    for tool in tools:
        print(f"- {tool.name}: {tool.description}")

Gerir Erros do MCP

Um servidor MCP é um processo ou um serviço remoto: pode falhar ao iniciar, perder a ligação ou ter um token expirado. Planeie um modo degradado em vez de deixar a exceção propagar-se até ao utilizador.

from agents.mcp import MCPServerStdio

async def create_agent_with_mcp():
    server = MCPServerStdio(
        name="External Service",
        command="npx",
        args=["-y", "my-mcp-server"],
    )

    try:
        async with server:
            agent = Agent(
                name="My Agent",
                instructions="Use the external service.",
                mcp_servers=[server],
            )
            result = await Runner.run(agent, "Execute the task.")
            return result.final_output
    except Exception as e:
        # Fallback sem MCP
        fallback_agent = Agent(
            name="My Agent (degraded mode)",
            instructions="The external service is unavailable. Inform the user.",
        )
        result = await Runner.run(fallback_agent, "The service is unavailable.")
        return result.final_output

O agente de fallback não finge funcionar: anuncia a indisponibilidade. Um agente que invente uma resposta quando a sua fonte de dados está indisponível custa muito mais do que aquele que admite não poder prosseguir.

Pontos-chave

  • O MCP é um protocolo aberto para ligar serviços externos ao seu agente
  • Utilize MCPServerStdio para servidores locais e MCPServerSse para servidores remotos
  • Os Conectores da OpenAI são integrações geridas na plataforma
  • Pode combinar ferramentas de função e servidores MCP no mesmo agente
  • Trate os erros de ligação do MCP com um modo degradado