Conexões MCP

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

Escolha a origem da conexão de acordo com o local de onde é possível acessar o servidor.

Conecte-se a partir da OpenAI

Adicione um servidor MCP com transporte HTTP a agent.tools. A OpenAI precisa ter acesso ao servidor. A conexão funciona com ou sem um ambiente de sessão.

Por exemplo, o servidor 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-se a partir do seu ambiente

O executor estabelece a conexão MCP a partir do ambiente da sessão. Use essa opção para acessar servidores em uma rede privada ou software instalado nesse ambiente.

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

Conecte-se via HTTP

Use HTTP para um servidor que já está em execução. Adicione a entrada abaixo a agent.tools e substitua a URL por um endereço que seu ambiente consiga acessar.

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

Nesse caso, uma URL com localhost aponta para o ambiente da sessão. Se você omitir connection_origin, a OpenAI estabelecerá a conexão.

Inicie um servidor via stdio

Use stdio para que o executor inicie o processo do 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 código do servidor em /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 usado pelo 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, informe command e um caminho absoluto em cwd. O campo args é opcional. Omita connection_origin.

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

Para servidores MCP que usam stdio e são hospedados pela OpenAI, omita a política de rede ou defina seu valor como enabled. Essas conexões não são compatíveis com as políticas de rede disabled e restricted.

Adicione autenticação

Se o servidor permitir acesso anônimo, omita os campos de autenticação e vault_ids. Caso contrário, escolha a origem das credenciais da conexão.

• Credenciais HTTP para uma única 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 MCP em um cofre e vincule-o à sessão por meio de vault_ids. A autenticação MCP com credenciais do cofre se aplica apenas a conexões originadas na OpenAI. A URL do servidor determina quais credenciais correspondem à conexão. Se houver mais de uma correspondência, use credential_id para selecionar a credencial.
• Credenciais para stdio. Defina os valores no ambiente e liste os nomes das variáveis em transport.env_vars. O código executado no ambiente pode ler esses valores. Sessões auto-hospedadas não aceitam valores definidos diretamente em transport.env.

Por exemplo, o transporte HTTP pode incluir um token de portador e um cabeçalho adicional.

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. Informe o valor diretamente na configuração ou use uma credencial do cofre que corresponda à URL. Você pode incluir outros cabeçalhos ao usar a autenticação com cofre. Conexões HTTP originadas no ambiente não usam credenciais do cofre. Configure a autenticação diretamente ou use um proxy confiável.

Não inclua segredos em definições reutilizáveis de agentes, arquivos de plugins ou logs. Para impedir que o código gerado pelo agente acesse as credenciais, use um proxy ou servidor confiável que as forneça fora do ambiente.

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

Defina allowed_tools para limitar as ferramentas que 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ões 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 que usam stdio, verifique também os logs do processo MCP.

• Acesso à rede. Verifique a URL e connection_origin. Para conexões originadas no ambiente, confirme que o executor está conectado e que a rede dele permite acessar o servidor.
• Credenciais. Verifique o token ou os cabeçalhos. Se usar um cofre, confirme que a credencial corresponde à URL do servidor.
• Executável e dependências. Verifique se o comando configurado pode ser executado no ambiente.
• Diretório de trabalho. Ao configurar stdio diretamente, informe em cwd o caminho absoluto de um diretório existente.

Guias relacionados

• Os plugins reúnem configurações MCP e habilidades em pacotes que podem ser reutilizados em várias sessões.
• O guia Pesquisa de ferramentas explica como funciona a descoberta automática de ferramentas MCP nos modelos e provedores compatíveis.