MCP e Conectores: Ligar Serviços Externos
Nesta página
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
MCPServerStdiopara servidores locais eMCPServerSsepara 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