Conexões MCP

Um servidor MCP publica definições de ferramentas e executa chamadas de ferramentas. A API de Agentes descobre as ferramentas, chama o servidor e retorna os resultados ao agente. Seu aplicativo não precisa lidar com cada chamada.

Escolha de onde a conexão será feita com base em onde o servidor pode ser acessado:

Conecte a partir da OpenAI

Adicione um servidor MCP HTTP a agent.tools. O servidor deve ser acessível a partir da OpenAI. Isso funciona com ou sem um ambiente de sessão.

Por exemplo, o MCP da documentação da OpenAI permite acesso anônimo:

12345678910{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": {
    "type": "http",
    "server_url": "https://developers.openai.com/mcp"
  },
  "connection_origin": "service",
  "required": true
}

Conecte a partir do seu ambiente

Um MCP do executor se conecta a partir do ambiente da sessão. Use-o para servidores em uma rede privada ou para software instalado nesse ambiente.

Defina environment.type da sessão como self_hosted ou openai_hosted. Para um ambiente auto-hospedado, conecte o executor antes que o agente use suas ferramentas.

Conecte via HTTP

Use HTTP para um servidor que já esteja em execução. Adicione esta entrada a agent.tools, substituindo a URL por um endereço que seu ambiente possa acessar:

12345678910{
  "type": "mcp",
  "server_label": "internal_search",
  "transport": {
    "type": "http",
    "server_url": "https://mcp.internal.example.com/search"
  },
  "connection_origin": "environment",
  "required": true
}

Aqui, uma URL localhost se refere ao ambiente da sessão. Se você omitir connection_origin, a conexão será feita pela OpenAI.

Inicie um servidor via stdio

Use stdio para permitir que o executor inicie um processo de servidor. Primeiro, instale o servidor e suas dependências no ambiente.

Para este exemplo de consulta de clientes, instale o SDK do MCP:

python3 -m venv /workspace/mcp-demo
/workspace/mcp-demo/bin/python -m pip install 'mcp==1.26.0'

Salve o servidor como /workspace/lookup_mcp.py:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import sys

from mcp.server.fastmcp import FastMCP

server = FastMCP("customer-lookup", host="127.0.0.1", port=8765, stateless_http=True)


@server.tool()
def get_customer(customer_id: str) -> dict:
    """Look up a customer in the example data."""
    customers = {"123": {"name": "Example Customer", "plan": "pro"}}
    return {"customer": customers.get(customer_id)}


if __name__ == "__main__":
    transport = sys.argv[1] if len(sys.argv) > 1 else "streamable-http"
    server.run(transport=transport)

Adicione o servidor a agent.tools. O argumento stdio seleciona o transporte do script:

1234567891011{
  "type": "mcp",
  "server_label": "customer_lookup",
  "transport": {
    "type": "stdio",
    "command": "/workspace/mcp-demo/bin/python",
    "args": ["/workspace/lookup_mcp.py", "stdio"],
    "cwd": "/workspace"
  },
  "required": true
}

Para stdio, command e um caminho absoluto em cwd são obrigatórios; args é opcional. Omita connection_origin.

Envie uma mensagem pedindo ao agente que consulte o cliente 123. A ferramenta retorna Example Customer, que está no plano pro.

Para MCPs stdio hospedados pela OpenAI, omita a política de rede ou defina-a como enabled. As políticas de rede disabled e restricted não são compatíveis com essas conexões.

Adicione autenticação

Para um servidor que permite acesso anônimo, omita os campos de autenticação e vault_ids. Caso contrário, escolha a origem das credenciais para sua conexão:

• Credenciais HTTP para uma sessão: Defina transport.authorization ou transport.headers ao criar a sessão. A API de Agentes criptografa esses valores e os omite do recurso de sessão retornado.
• Credenciais HTTP reutilizáveis: Armazene as credenciais em um cofre e anexe-o por meio de vault_ids. Os cofres se aplicam apenas a conexões feitas a partir da OpenAI. As credenciais são selecionadas por correspondência com a URL do servidor; use credential_id para selecionar uma quando houver várias correspondências.
• Credenciais stdio: Forneça os valores no ambiente e liste seus nomes em transport.env_vars. Esses valores podem ser lidos por código executado no ambiente. Sessões auto-hospedadas não aceitam valores definidos diretamente em transport.env.

Por exemplo, um transporte HTTP pode incluir um token bearer e outro cabeçalho:

123456{
  "type": "http",
  "server_url": "https://mcp.example.com/mcp",
  "authorization": "Bearer YOUR_MCP_ACCESS_TOKEN",
  "headers": { "X-Tenant-ID": "tenant_123" }
}

Use uma única origem para Authorization: a configuração direta ou uma credencial correspondente no cofre. Outros cabeçalhos podem acompanhar a autenticação por cofre. Conexões HTTP originadas no ambiente não usam credenciais do cofre; use autenticação definida diretamente na configuração ou um proxy confiável.

Mantenha segredos fora de definições reutilizáveis de agentes, arquivos de plug-ins e logs. Para manter as credenciais inacessíveis ao código gerado pelo agente, use um proxy ou servidor confiável que as forneça fora do ambiente.

Controle o acesso às ferramentas e a inicialização

Defina allowed_tools para limitar quais ferramentas o agente pode descobrir e chamar. Defina required: true para que o turno falhe se o servidor não conseguir inicializar. Por padrão, a inicialização é opcional.

Consulte a referência de criação de sessão para ver todos os campos de configuração do MCP.

Solucione problemas de conexão

Se um servidor obrigatório não conseguir inicializar, examine o erro em agent.session.turn.failed. Para servidores stdio, verifique também os logs do processo MCP.

• Acesso à rede: Verifique a URL e connection_origin. Para conexões a partir do ambiente, verifique se o executor está conectado e se a rede dele consegue acessar o servidor.
• Credenciais: Verifique o token ou os cabeçalhos. No caso de um cofre, verifique se a credencial corresponde à URL do servidor.
• Executável e dependências: Verifique se o comando configurado é executado dentro do ambiente.
• Diretório de trabalho: Use em cwd o caminho absoluto de um diretório existente para uma configuração stdio definida diretamente.

Guias relacionados

• Plug-ins agrupam configurações MCP e habilidades para reutilização entre sessões.
• Pesquisa de ferramentas explica a descoberta automática de ferramentas MCP em modelos e provedores compatíveis.