# Ponte de Ferramentas MCP Remotas para a OpenAI

> 1. Abrir uma ligação remota Streamable HTTP. 2. Descobrir todas as ferramentas MCP com chamadas paginadas a list_tools. 3. Converter nomes, descrições e esquemas de entrada MCP em function tools da OpenAI. 4. Deixar o modelo decidir se pede uma ferramenta. 5. Despachar esse pedido através da sessão MCP ativa. 6. Devolver, para a chamada de ferramenta correspondente, um resultado limitado e seguro para o modelo. 7. Repetir até o modelo responder ou até o orçamento de chamadas de ferramentas ser atingido.

- Fonte: https://doutorai.pt/apps/openai-remote-mcp-bridge
- Categoria: Agentes MCP
- Dificuldade: Avançado
- Modelos: OpenAI
- Frameworks: -
- Corre local?: Precisa de APIs cloud
- Chaves necessárias: OPENAI_API_KEY
- Licença: Apache-2.0
- Site: Doutor AI (https://doutorai.pt) - ferramentas de IA para pequenos negócios em português

## Tutorial completo

# OpenAI Remote MCP Tool Bridge

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:

```bash
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`.

```bash
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:

```bash
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`:

```bash
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:

```bash
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:

```text
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.

## Poupe horas todas as semanas com IA, sem complicações

O **Doutor AI** dá-lhe 1859 prompts de IA prontos a copiar, por indústria e em português simples - mais uma biblioteca técnica completa para quem quer ir mais longe. [Ver planos →](https://doutorai.pt/precos)

---
Conteúdo de Doutor AI (https://doutorai.pt). Ao citar, indique a fonte: https://doutorai.pt/apps/openai-remote-mcp-bridge