Ponte de Ferramentas MCP Remotas para a OpenAI

Aprenda a ligar um loop simples de function calling da OpenAI a um servidor MCP Streamable HTTP alojado, sem recorrer a um framework de agentes.

O script mantém toda a ponte visível:

1. Abra uma ligação remota Streamable HTTP.
2. Descubra todas as ferramentas MCP com chamadas paginadas a list_tools().
3. Converta os nomes, as descrições e os esquemas de entrada do MCP em function tools da OpenAI.
4. Deixe o modelo decidir se pretende pedir uma ferramenta.
5. Encaminhe esse pedido através da sessão MCP ativa.
6. Devolva um resultado limitado e seguro para o modelo, relativo à chamada de ferramenta correspondente.
7. Repita até que o modelo responda ou até que o limite de chamadas de ferramentas seja atingido.

Configuração

Use Python 3.11 ou superior:

pip install -r requirements.txt
export OPENAI_API_KEY="your-openai-api-key"

O servidor predefinido é o Parallel Search MCP em https://search.parallel.ai/mcp, um endpoint alojado executável que expõe ferramentas apenas de leitura sem autenticação MCP.

Descobrir ferramentas sem OpenAI

O --list-tools liga-se ao servidor e imprime os nomes e as descrições atuais das ferramentas. Não requer OPENAI_API_KEY.

env -u OPENAI_API_KEY python openai_remote_mcp_bridge.py --list-tools

Executar a bridge

Utilize uma tarefa que precise de informação atualizada, para que o modelo tenha um motivo natural para chamar uma ferramenta remota:

python openai_remote_mcp_bridge.py \
  "Read https://news.ycombinator.com/ now. What is the title and destination URL of the number-one story?"

O rastreio mostra [connect], [discover], [convert], cada pedido do OpenAI para o MCP, cada resultado do MCP para o OpenAI e [final].

Por predefinição, o modelo recebe todas as ferramentas compatíveis descobertas no servidor fidedigno. Para expor apenas um subconjunto, copie os nomes de --list-tools:

python openai_remote_mcp_bridge.py \
  --tools tool_name_one,tool_name_two \
  "Complete a task that needs those tools."

Também pode alterar o modelo, o servidor ou o orçamento total de chamadas solicitadas:

python openai_remote_mcp_bridge.py \
  --server-url https://your-trusted-server.example/mcp \
  --model gpt-4o-mini \
  --max-tool-calls 3 \
  "Complete a task with current information."

MCP_SERVER_URL e OPENAI_MODEL fornecem valores predefinidos, através de variáveis de ambiente, para as flags correspondentes.

O que a conversão faz

Para cada ferramenta MCP exposta, a bridge mapeia:

MCP tool.name        -> OpenAI function.name
MCP tool.description -> OpenAI function.description
MCP tool.inputSchema -> OpenAI function.parameters

Os nomes de funções da OpenAI devem conter entre 1 e 64 letras, números, underscores ou hífenes. O schema de entrada do MCP deve descrever um objeto JSON de nível superior. A bridge falha de imediato com o nome da ferramenta incompatível, em vez de alterar silenciosamente o seu contrato.

Os resultados das ferramentas dão preferência ao structuredContent do MCP. Caso contrário, os blocos de texto são concatenados; os payloads de imagem, áudio e outros conteúdos não textuais são substituídos por marcadores compactos. O output demasiado extenso é truncado antes de entrar no contexto do modelo.

Cada chamada de ferramenta solicitada conta para o --max-tool-calls, incluindo pedidos malformados, desconhecidos, falhados e ignorados. Cada pedido recebe uma resposta de ferramenta correspondente, e o modelo recebe um último turno sem ferramentas quando o orçamento se esgota.

Âmbito e segurança

Este tutorial suporta intencionalmente um único servidor MCP Streamable HTTP fidedigno, não autenticado e apenas de leitura. Inspecione um servidor com --list-tools antes de o expor ao modelo.

As questões de produção deliberadamente excluídas deste exemplo incluem OAuth, aprovação de ferramentas de escrita, encaminhamento entre múltiplos servidores, recursos e prompts do MCP, e conversão universal de JSON Schema. Adicione essas políticas à sua aplicação, em vez de tratar --tools como um limite de autorização.

Resolução de problemas

• OPENAI_API_KEY is required: exporte uma chave, ou use --list-tools para testar o MCP sem OpenAI.
• Unknown MCP tool: execute --list-tools com o mesmo --server-url e atualize --tools.
• not a valid OpenAI function name ou must have an object input schema: o servidor selecionado expõe uma ferramenta que não pode ser representada diretamente como uma ferramenta de função da OpenAI.
• Bridge failed: verifique se o servidor usa Streamable HTTP, se está acessível sem autenticação MCP e se se destina a utilização apenas de leitura.