MCP Bridge API

Um proxy RESTful leve e agnóstico a LLMs que unifica múltiplos servidores MCP sob uma única API.

Documentação

MCP Bridge API

Um Proxy RESTful Leve e Agnóstico de LLM para Servidores Model Context Protocol

Figura: A interface do React Native MCP Agent mostrando a tela de chat com resultados de execução de ferramentas (à esquerda) e a tela de configurações com o status da conexão MCP Bridge e a configuração da API Gemini (à direita)

Autores:
Arash Ahmadi, Sarah S. Sharif e Yaser M. Banad*
Escola de Engenharia Elétrica e de Computação, Universidade de Oklahoma, Oklahoma, Estados Unidos
*Autor correspondente: bana@ou.edu

Se você quiser referenciar este projeto de pesquisa em seu trabalho, cite nosso artigo:

@article{ahmadi2025mcp,
  title={MCP Bridge: A Lightweight, LLM-Agnostic RESTful Proxy for Model Context Protocol Servers},
  author={Ahmadi, Arash and Sharif, Sarah and Banad, Yaser M},
  journal={arXiv preprint arXiv:2504.08999},
  year={2025}
}

📋 Sumário

📚 Introdução
🏗️ Arquitetura
💾 Instalação
🐍 Agente Python MCP-Gemini
📱 Agente React Native MCP
⚙️ Configuração
🧪 Uso da API
🔐 Níveis de Risco
🌟 Impacto na Comunidade e Reconhecimento
📋 Registro de Alterações
🚧 Considerações de Implantação
📊 Comparação com Outros Repositórios de MCP Bridge/Proxy
📝 Licença

📚 Introdução

MCP Bridge é um proxy leve, rápido e agnóstico de LLM que se conecta a múltiplos servidores Model Context Protocol (MCP) e expõe suas capacidades por meio de uma API REST unificada. Ele permite que qualquer cliente em qualquer plataforma aproveite a funcionalidade MCP sem restrições de execução de processos. Diferentemente do SDK MCP oficial da Anthropic, o MCP Bridge é totalmente independente e projetado para funcionar com qualquer backend de LLM, o que o torna adaptável, modular e à prova do futuro para diversas implantações. Com níveis de execução opcionais baseados em risco, ele fornece controles de segurança granulares—desde execução padrão até fluxos de confirmação e isolamento Docker—mantendo compatibilidade retroativa com clientes MCP padrão.

Complementando essa infraestrutura do lado do servidor, há duas implementações distintas de clientes inteligentes:

Agente Python MCP-Gemini - Um cliente Python de linha de comando para ambientes desktop
Agente React Native MCP - Um aplicativo móvel moderno e multiplataforma

Ambos os clientes permitem interação em linguagem natural com ferramentas MCP por meio de interfaces inteligentes alimentadas por LLM, que apresentam raciocínio em múltiplas etapas para operações complexas, tratamento de fluxos de confirmação de segurança e opções de exibição configuráveis para maior usabilidade. Juntos, as capacidades versáteis do lado do servidor do MCP Bridge e essas interfaces de cliente inteligentes criam um ecossistema poderoso para o desenvolvimento de aplicações sofisticadas alimentadas por LLM.

⚠️ O Problema

Muitos servidores MCP usam transportes STDIO que exigem execução local de processos
Dispositivos de borda, dispositivos móveis, navegadores web e outras plataformas não conseguem executar eficientemente servidores MCP npm ou Python
Conexões diretas a servidores MCP são impraticáveis em ambientes com recursos limitados
Múltiplos clientes isolados conectando-se aos mesmos servidores causa redundância e aumenta o uso de recursos
Interagir diretamente com ferramentas MCP exige conhecimento técnico dos formatos e requisitos específicos das ferramentas

🏗️ Arquitetura

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  React Native   │     │     Python      │     │  Other Clients  │
│   MCP Agent     │     │  Gemini Agent   │     │                 │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         │                       │                       │
         │                       ▼                       │
         │           ┌───────────────────────┐          │
         └──────────►│                       │◄─────────┘
                     │      REST API         │
                     │                       │
                     └───────────┬───────────┘
                                 │
                                 ▼
                     ┌───────────────────────┐
                     │                       │
                     │     MCP Bridge        │
                     │                       │
                     └───────────┬───────────┘
                                 │
                 ┌───────────────┼───────────────┐
                 │               │               │
                 ▼               ▼               ▼
        ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
        │  MCP Server │  │  MCP Server │  │  MCP Server │
        │    (STDIO)  │  │    (STDIO)  │  │    (SSE)    │
        └─────────────┘  └─────────────┘  └─────────────┘

💾 Instalação

📦 Pré-requisitos

Node.js 18+ para MCP Bridge
Python 3.8+ para o Agente Python MCP-Gemini
Ambiente de desenvolvimento React Native para o aplicativo móvel

🚀 Configuração Rápida

MCP Bridge

# Install dependencies
npm install express cors morgan uuid

# Start the server
node mcp-bridge.js

Agente Python MCP-Gemini

# Install dependencies
pip install google-generativeai requests rich

# Start the agent
python llm_test.py

Agente React Native MCP

# Navigate to the React Native app directory
cd reactnative-gamini-mcp-agent

# Install dependencies
npm install

# Start the development server
npx expo start

🐍 Agente Python MCP-Gemini

O Agente Python MCP-Gemini é um cliente de linha de comando que se conecta ao MCP Bridge e usa o LLM Gemini do Google para processar solicitações do usuário e executar comandos de ferramentas MCP. Ele é projetado para ambientes desktop e fluxos de trabalho de desenvolvedores.

Principais Recursos

Raciocínio em múltiplas etapas - Suporta chamadas de ferramentas sequenciadas para operações complexas
Fluxo de confirmação de segurança - Tratamento integrado para operações de risco médio e alto
Exibição JSON flexível - Controle a verbosidade das saídas JSON para melhor legibilidade
Conexão configurável - Conecte-se a qualquer instância do MCP Bridge com URL e porta personalizadas
Descoberta de ferramentas disponíveis - Detecta e usa automaticamente todas as ferramentas dos servidores conectados

Configuração do Agente Python

O Agente Python MCP-Gemini suporta várias opções de linha de comando:

usage: llm_test.py [-h] [--hide-json] [--json-width JSON_WIDTH] [--mcp-url MCP_URL] [--mcp-port MCP_PORT]

MCP-Gemini Agent with configurable settings

options:
  -h, --help            show this help message and exit
  --hide-json           Hide JSON results from tool executions
  --json-width JSON_WIDTH
                        Maximum width for JSON output (default: 100)
  --mcp-url MCP_URL     MCP Bridge URL including protocol and port (default: http://localhost:3000)
  --mcp-port MCP_PORT   Override port in MCP Bridge URL (default: use port from --mcp-url)

Exemplos de Uso do Agente Python

# Basic usage with default settings
python llm_test.py

# Hide JSON results for cleaner output
python llm_test.py --hide-json

# Connect to a custom MCP Bridge server
python llm_test.py --mcp-url http://192.168.1.100:3000

# Connect to a different port
python llm_test.py --mcp-port 4000

# Adjust JSON width display for better formatting
python llm_test.py --json-width 120

📱 Agente React Native MCP

O Agente React Native MCP é um aplicativo móvel moderno e multiplataforma que fornece acesso intuitivo às ferramentas MCP por meio de uma interface limpa e amigável. Construído com Expo e React Native Paper, ele oferece uma interface Material Design 3 com tema escuro, otimizada para plataformas iOS e Android.

Principais Recursos

Compatibilidade multiplataforma: Funciona em plataformas iOS, Android e web
Interface de chat intuitiva: Interação em linguagem natural com exibição de mensagens segmentadas
Execução de ferramentas em tempo real: Feedback visual para chamadas de ferramentas MCP com seções de resultados recolhíveis
Gerenciamento de conversas: Histórico de conversas persistente com títulos gerados por IA
UI/UX moderna: Tema escuro com efeitos de glassmorphism e animações suaves
Configurações abrangentes: Configuração fácil das conexões MCP Bridge e das configurações da API Gemini
Integração de segurança: Suporte integrado para fluxos de confirmação de nível de risco do MCP Bridge
Suporte a múltiplos modelos: Compatível com vários modelos Gemini, incluindo o mais recente 2.5 Flash Preview

Primeiros Passos com o aplicativo React Native

Configure o MCP Bridge: Defina a URL do seu servidor MCP Bridge na aba Configurações
Adicione a chave da API Gemini: Insira sua chave da API Google Gemini para funcionalidade de IA
Selecione o modelo: Escolha entre os modelos Gemini disponíveis, incluindo os lançamentos mais recentes
Comece a conversar: Inicie conversas em linguagem natural com suas ferramentas MCP

O aplicativo descobre automaticamente as ferramentas MCP disponíveis e fornece assistência contextual para operações complexas de múltiplas etapas.

⚙️ Configuração

Configuração do MCP Bridge

O MCP Bridge é configurado por meio de um arquivo JSON chamado mcp_config.json na raiz do projeto. Este é um exemplo de uma configuração MCP básica:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
      "riskLevel": 2
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "your-slack-token",
        "SLACK_TEAM_ID": "your-team-id"
      },
      "riskLevel": 1
    }
  }
}

🧪 Uso da API

O MCP Bridge expõe uma API REST limpa e intuitiva para interagir com servidores conectados. Aqui está um detalhamento dos endpoints disponíveis:

📋 Endpoints Gerais

Endpoint	Método	Descrição
`/servers`	GET	Lista todos os servidores MCP conectados
`/servers`	POST	Inicia um novo servidor MCP
`/servers/{serverId}`	DELETE	Para e remove um servidor MCP
`/health`	GET	Obtém o status de saúde do MCP Bridge
`/confirmations/{confirmationId}`	POST	Confirma a execução de uma solicitação de nível de risco médio

📌 Endpoints Específicos do Servidor

Endpoint	Método	Descrição
`/servers/{serverId}/tools`	GET	Lista todas as ferramentas de um servidor específico
`/servers/{serverId}/tools/{toolName}`	POST	Executa uma ferramenta específica
`/servers/{serverId}/resources`	GET	Lista todos os recursos
`/servers/{serverId}/resources/{resourceUri}`	GET	Recupera o conteúdo de um recurso específico
`/servers/{serverId}/prompts`	GET	Lista todos os prompts
`/servers/{serverId}/prompts/{promptName}`	POST	Executa um prompt com argumentos

🧪 Exemplos de Solicitações

📂 Ler Diretório (Sistema de Arquivos)

POST /servers/filesystem/tools/list_directory
Content-Type: application/json

{
  "path": "."
}

🧪 Recursos do Cliente

Recursos do Agente Python

O Agente Python MCP-Gemini fornece:

Raciocínio em múltiplas etapas - Suporta chamadas de ferramentas sequenciadas para operações complexas
Fluxo de confirmação de segurança - Tratamento integrado para operações de risco médio e alto
Exibição JSON flexível - Controle a verbosidade das saídas JSON para melhor legibilidade
Conexão configurável - Conecte-se a qualquer instância do MCP Bridge com URL e porta personalizadas
Descoberta de ferramentas disponíveis - Detecta e usa automaticamente todas as ferramentas dos servidores conectados

Recursos do Agente React Native

O Agente React Native MCP fornece:

Gerenciamento de conversas - Histórico de chat persistente com títulos gerados por IA
Exibição de mensagens segmentadas - Separação limpa de respostas de texto e operações de ferramentas
Execução de ferramentas em tempo real - Feedback visual com seções de resultados recolhíveis
Interface de confirmação de segurança - Diálogos de confirmação nativos para operações de risco médio/alto
Suporte a múltiplos modelos - Suporte para vários modelos Gemini com troca fácil
Multiplataforma - Funciona em plataformas iOS, Android e web
Material Design moderno - Tema escuro com animações suaves e feedback tátil

🔐 Níveis de Risco

O MCP Bridge implementa um sistema opcional de níveis de risco que fornece controle sobre os comportamentos de execução do servidor. Os níveis de risco ajudam a gerenciar preocupações de segurança e recursos ao executar operações potencialmente sensíveis do servidor MCP.

Classificação dos Níveis de Risco

Nível	Nome	Descrição	Comportamento
1	Baixo	Execução padrão	Execução direta sem confirmação
2	Médio	Requer confirmação	O cliente deve confirmar a execução antes do processamento
3	Alto	Execução Docker necessária	O servidor é executado em contêiner Docker isolado

Configurando Níveis de Risco

Os níveis de risco são opcionais para compatibilidade retroativa. Você pode configurar os níveis de risco no seu mcp_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
      "riskLevel": 2
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "your-slack-token",
        "SLACK_TEAM_ID": "your-team-id"
      },
      "riskLevel": 1
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      },
      "riskLevel": 3,
      "docker": {
        "image": "node:18",
        "volumes": ["/tmp:/tmp"],
        "network": "host"
      }
    }
  }
}

Fluxos de Trabalho dos Níveis de Risco

Risco Baixo (Nível 1)

Execução padrão sem etapas adicionais
Adequado para operações com preocupações mínimas de segurança
Este é o comportamento padrão quando nenhum nível de risco é especificado

Risco Médio (Nível 2)

O cliente faz uma solicitação de execução de ferramenta
O servidor responde com uma solicitação de confirmação contendo um ID de confirmação
O cliente deve fazer uma solicitação de confirmação separada para prosseguir
Somente após a confirmação o servidor executa a operação

Tanto o Agente Python MCP-Gemini quanto o Agente React Native lidam com esse fluxo de confirmação automaticamente, solicitando a aprovação do usuário quando necessário.

Risco Alto (Nível 3)

O servidor é executado automaticamente em um contêiner Docker isolado
Fornece isolamento ambiental para o processo do servidor MCP
Requer que o Docker esteja instalado e configurado corretamente

📋 Registro de Alterações

Atualizações Recentes

✅ Suporte ao Gerenciador de Pacotes UV: Corrigido o problema com o carregamento de servidores MCP baseados em UV (Python). O MCP Bridge agora inicializa e se comunica corretamente com servidores MCP Python que usam o gerenciador de pacotes UV, resolvendo problemas anteriores de compatibilidade com toolchains baseados em UV.
📱 Agente React Native MCP: Adicionado um aplicativo móvel abrangente com:
- Suporte multiplataforma para iOS, Android e web
- Interface Material Design 3 moderna com tema escuro
- Gerenciamento inteligente de conversas com títulos gerados por IA
- Execução de ferramentas em tempo real com feedback visual
- Fluxos de confirmação de segurança integrados
- Suporte para vários modelos Gemini, incluindo os lançamentos mais recentes
🔧 Execução de Ferramentas Aprimorada: Melhoradas as capacidades de raciocínio em múltiplas etapas em todos os clientes
🛡️ Melhorias de Segurança: Fluxos de confirmação de nível de risco aprimorados com melhor experiência do usuário
📊 Melhor Tratamento de Erros: Mecanismos de tratamento e recuperação de erros mais robustos

🌟 Impacto na Comunidade e Reconhecimento

O MCP Bridge ganhou reconhecimento nas comunidades de IA e desenvolvimento, sendo apresentado em pesquisas acadêmicas, análises de segurança da indústria, discursos profissionais e publicações técnicas. Esses reconhecimentos destacam o valor prático e o impacto no mundo real da nossa solução de proxy leve e agnóstica de LLM.

Citado por este artigo: From Prompt Injections to Protocol Exploits: Threats in LLM-Powered AI Agents Workflows - Um artigo de pesquisa discutindo implicações de segurança em fluxos de trabalho de agentes de IA alimentados por LLM

Briefing de Pesquisa: Segurança MCP - Pesquisa de segurança da Wiz destacando o MCP Bridge como um exemplo de trabalho acadêmico no ecossistema MCP

*[Publicação no LinkedIn por Vaibhava Lakshmi Ravideshik](https://www.linkedin.com/posts/vaibhava-lakshmi-ravideshik_aiintegration-modelcontextprotocol-llm-activity-7344581233097547777-IktU/) - Discussão de um instrutor do LinkedIn Learning sobre as aplicações práticas do MCP Bridge* Medium Technical Article

Desbloqueando aplicativos agênticos com o Model Context Protocol (MCP) para serviços financeiros - Artigo do Medium apresentando o padrão de design do MCP Bridge para aplicações financeiras

🚧 Considerações de implantação

🔒 Segurança

Use HTTPS em produção
Adicione autenticação para operações sensíveis
Isole em rede os serviços críticos

📊 Escalonamento

Use balanceadores de carga
Agrupe servidores de alta demanda
Monitore métricas e pressão de recursos

📱 Implantação móvel

Para o aplicativo React Native:

Compile para produção usando npx expo build
Configure a implantação na loja de aplicativos com EAS Build
Configure atualizações over-the-air com EAS Update

📊 Comparação com outros repositórios MCP Bridge/Proxy

Recurso	`ivanboring/mcp-rest`	`INQUIRELAB/mcp-bridge-api` (Este repositório)	`SecretiveShell/MCP-Bridge`	`JoshuaRileyDev/mcp-api`	`rakesh-eltropy/mcp-client`	`bartolli/mcp-llm-bridge`
⚙️ Linguagem principal	Node.js	Node.js (Bridge) + Python (Agente) ✨	Python	Node.js	Python	Python
🎯 Objetivo principal	Wrapper REST simples	Bridge REST independente de LLM + Agente Gemini	Bridge OpenAI e REST rico em recursos + Servidor MCP	API REST para servidores MCP + Exemplo de UI de chat	Agente LangChain com ferramentas MCP (REST/CLI)	Bridge LLM MCP <-> (compatível com OpenAI)
🔌 Conexão MCP	Somente SSE	STDIO (gerenciado) + Docker (baseado em risco) ✔️	STDIO, SSE, Docker	STDIO	STDIO (LangChain)	STDIO
🚀 Interface de API	REST básico	API REST unificada ✔️	Compatível com OpenAI, REST, Servidor MCP (SSE)	API REST + Swagger	API REST (streaming), CLI	CLI interativo
✨ Recursos principais	Lista/chamada básica de ferramentas	Multisservidor, níveis de risco, confirmação de segurança, execução Docker, agente Gemini, flexibilidade de configuração ✨	Compatível com OpenAI, amostragem, multitransporte, autenticação, Docker/Helm, configuração flexível	Multisservidor, normalização de nomes de ferramentas, Swagger, UI de chat	Integração LangChain, REST/CLI, streaming	Tradução bidirecional de protocolo, ferramenta de banco de dados
🔧 Configuração	Argumentos de CLI	Arquivo JSON + variáveis de ambiente ✔️	Arquivo JSON, URL HTTP, variáveis de ambiente	Arquivo JSON (busca em vários caminhos), variáveis de ambiente	Arquivo JSON	Objeto Python, variáveis de ambiente
🧩 Integração com LLM	Nenhuma	Sim (agente Gemini dedicado com raciocínio em várias etapas) ✨	Sim (endpoint OpenAI)	Nenhuma (somente API)	Sim (LangChain)	Sim (cliente OpenAI)
🏗️ Complexidade	Baixa	Baixa ✔️	Alta	Moderada	Moderada-alta	Moderada
🛡️ Recursos de segurança	Nenhum	Níveis de risco (médio/alto) + fluxo de confirmação + isolamento Docker ✨	Autenticação básica (chaves de API), CORS	Nenhum	Nenhum	Nenhum
📦 Dependências principais	`express`, `mcp-client`	`express`, `uuid` (Bridge, dependência mínima); `requests`, `google-genai`, `rich` (Agente)	`fastapi`, `mcp`, `mcpx`	`express`, `@mcp/sdk`, `socket.io`	`fastapi`, `

Escopo da licença

O código original do INQUIRE Lab é licenciado sob a PolyForm Noncommercial License 1.0.0. Os conjuntos de dados, figuras e documentação originais do INQUIRE Lab são licenciados sob CC BY-NC 4.0. Consulte LICENSE para o escopo e os textos completos das licenças. Materiais de outros detentores de direitos mantêm seus termos originais.