MCP Bridge API

Un proxy RESTful ligero y agnóstico al LLM que unifica múltiples servidores MCP bajo una sola API.

Documentación

MCP Bridge API

Un Proxy RESTful Ligero y Agnóstico de LLM para Servidores del Protocolo de Contexto de Modelo (MCP)

Figura: La interfaz del Agente MCP de React Native mostrando la pantalla de chat con resultados de ejecución de herramientas (izquierda) y la pantalla de configuración con el estado de conexión de MCP Bridge y la configuración de la API de Gemini (derecha)

Autores:
Arash Ahmadi, Sarah S. Sharif, y Yaser M. Banad*
Escuela de Ingeniería Eléctrica y de Computación, Universidad de Oklahoma, Oklahoma, Estados Unidos
*Autor de correspondencia: bana@ou.edu

Si deseas referenciar este proyecto de investigación en tu trabajo, por favor cita nuestro artículo:

@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}
}

📋 Tabla de Contenidos

📚 Introducción
🏗️ Arquitectura
💾 Instalación
🐍 Agente MCP-Gemini en Python
📱 Agente MCP de React Native
⚙️ Configuración
🧪 Uso de la API
🔐 Niveles de Riesgo
🌟 Impacto Comunitario y Reconocimiento
📋 Registro de Cambios
🚧 Consideraciones de Despliegue
📊 Comparación con Otros Repositorios de MCP Bridge/Proxy
📝 Licencia

📚 Introducción

MCP Bridge es un proxy ligero, rápido y agnóstico de LLM que se conecta a múltiples servidores del Protocolo de Contexto de Modelo (MCP) y expone sus capacidades a través de una API REST unificada. Permite que cualquier cliente en cualquier plataforma aproveche la funcionalidad de MCP sin restricciones de ejecución de procesos. A diferencia del SDK oficial de MCP de Anthropic, MCP Bridge es completamente independiente y está diseñado para funcionar con cualquier backend de LLM, lo que lo hace adaptable, modular y a prueba de futuro para diversos despliegues. Con niveles de ejecución basados en riesgo opcionales, proporciona controles de seguridad granulares—desde ejecución estándar hasta flujos de confirmación y aislamiento con Docker—mientras mantiene compatibilidad hacia atrás con clientes MCP estándar.

Complementando esta infraestructura del lado del servidor, hay dos implementaciones de clientes inteligentes distintas:

Agente MCP-Gemini en Python - Un cliente Python de línea de comandos para entornos de escritorio
Agente MCP de React Native - Una aplicación móvil moderna multiplataforma

Ambos clientes permiten la interacción en lenguaje natural con herramientas MCP a través de interfaces inteligentes impulsadas por LLM que cuentan con razonamiento de múltiples pasos para operaciones complejas, manejo de flujos de confirmación de seguridad y opciones de visualización configurables para una mayor usabilidad. Juntos, las capacidades versátiles del lado del servidor de MCP Bridge y estas interfaces de cliente inteligentes crean un ecosistema poderoso para desarrollar aplicaciones sofisticadas impulsadas por LLM.

⚠️ El Problema

Muchos servidores MCP utilizan transportes STDIO que requieren ejecución de procesos locales
Dispositivos periféricos, dispositivos móviles, navegadores web y otras plataformas no pueden ejecutar eficientemente servidores MCP de npm o Python
Las conexiones directas a servidores MCP son poco prácticas en entornos con recursos limitados
Múltiples clientes aislados conectándose a los mismos servidores causa redundancia y aumenta el uso de recursos
Interactuar directamente con herramientas MCP requiere conocimiento técnico de formatos y requisitos específicos de las herramientas

🏗️ Arquitectura

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

💾 Instalación

📦 Requisitos Previos

Node.js 18+ para MCP Bridge
Python 3.8+ para el Agente MCP-Gemini en Python
Entorno de desarrollo de React Native para la aplicación móvil

🚀 Configuración Rápida

MCP Bridge

# Install dependencies
npm install express cors morgan uuid

# Start the server
node mcp-bridge.js

Agente MCP-Gemini en Python

# Install dependencies
pip install google-generativeai requests rich

# Start the agent
python llm_test.py

Agente MCP de React Native

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

# Install dependencies
npm install

# Start the development server
npx expo start

🐍 Agente MCP-Gemini en Python

El Agente MCP-Gemini en Python es un cliente de línea de comandos que se conecta a MCP Bridge y utiliza el LLM Gemini de Google para procesar solicitudes de usuario y ejecutar comandos de herramientas MCP. Está diseñado para entornos de escritorio y flujos de trabajo de desarrolladores.

Características Clave

Razonamiento de múltiples pasos - Soporta llamadas de herramientas secuenciadas para operaciones complejas
Flujo de confirmación de seguridad - Manejo integrado para operaciones de riesgo medio y alto
Visualización JSON flexible - Controla la verbosidad de las salidas JSON para una mejor legibilidad
Conexión configurable - Conéctate a cualquier instancia de MCP Bridge con URL y puerto personalizados
Descubrimiento de herramientas disponibles - Detecta y utiliza automáticamente todas las herramientas de los servidores conectados

Configuración del Agente Python

El Agente MCP-Gemini en Python soporta varias opciones de línea de comandos:

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)

Ejemplos de Uso del 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 MCP de React Native

El Agente MCP de React Native es una aplicación móvil moderna y multiplataforma que proporciona acceso intuitivo a herramientas MCP a través de una interfaz limpia y fácil de usar. Construido con Expo y React Native Paper, ofrece una interfaz de Material Design 3 con tema oscuro optimizada para plataformas iOS y Android.

Características Clave

Compatibilidad Multiplataforma: Funciona en plataformas iOS, Android y web
Interfaz de Chat Intuitiva: Interacción en lenguaje natural con visualización de mensajes segmentados
Ejecución de Herramientas en Tiempo Real: Retroalimentación visual para llamadas de herramientas MCP con secciones de resultados plegables
Gestión de Conversaciones: Historial de conversaciones persistente con títulos generados por IA
UI/UX Moderna: Tema oscuro con efectos de glassmorphism y animaciones suaves
Configuración Integral: Configuración fácil de conexiones de MCP Bridge y ajustes de la API de Gemini
Integración de Seguridad: Soporte integrado para los flujos de confirmación de niveles de riesgo de MCP Bridge
Soporte Multi-Modelo: Compatible con varios modelos de Gemini, incluido el último 2.5 Flash Preview

Comenzando con la aplicación React Native

Configura MCP Bridge: Establece la URL de tu servidor MCP Bridge en la pestaña de Configuración
Agrega la Clave de API de Gemini: Ingresa tu clave de API de Google Gemini para la funcionalidad de IA
Selecciona el Modelo: Elige entre los modelos de Gemini disponibles, incluidos los últimos lanzamientos
Comienza a Chatear: Inicia conversaciones en lenguaje natural con tus herramientas MCP

La aplicación descubre automáticamente las herramientas MCP disponibles y proporciona asistencia contextual para operaciones complejas de múltiples pasos.

⚙️ Configuración

Configuración de MCP Bridge

MCP Bridge se configura a través de un archivo JSON llamado mcp_config.json en la raíz del proyecto. Este es un ejemplo de una configuración 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 de la API

MCP Bridge expone una API REST limpia e intuitiva para interactuar con servidores conectados. Aquí hay un desglose de los endpoints disponibles:

📋 Endpoints Generales

Endpoint	Método	Descripción
`/servers`	GET	Lista todos los servidores MCP conectados
`/servers`	POST	Inicia un nuevo servidor MCP
`/servers/{serverId}`	DELETE	Detiene y elimina un servidor MCP
`/health`	GET	Obtiene el estado de salud de MCP Bridge
`/confirmations/{confirmationId}`	POST	Confirma la ejecución de una solicitud de nivel de riesgo medio

📌 Endpoints Específicos del Servidor

Endpoint	Método	Descripción
`/servers/{serverId}/tools`	GET	Lista todas las herramientas de un servidor específico
`/servers/{serverId}/tools/{toolName}`	POST	Ejecuta una herramienta específica
`/servers/{serverId}/resources`	GET	Lista todos los recursos
`/servers/{serverId}/resources/{resourceUri}`	GET	Recupera el contenido de un recurso específico
`/servers/{serverId}/prompts`	GET	Lista todos los prompts
`/servers/{serverId}/prompts/{promptName}`	POST	Ejecuta un prompt con argumentos

🧪 Ejemplos de Solicitudes

📂 Leer Directorio (Sistema de Archivos)

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

{
  "path": "."
}

🧪 Características del Cliente

Características del Agente Python

El Agente MCP-Gemini en Python proporciona:

Razonamiento de múltiples pasos - Soporta llamadas de herramientas secuenciadas para operaciones complejas
Flujo de confirmación de seguridad - Manejo integrado para operaciones de riesgo medio y alto
Visualización JSON flexible - Controla la verbosidad de las salidas JSON para una mejor legibilidad
Conexión configurable - Conéctate a cualquier instancia de MCP Bridge con URL y puerto personalizados
Descubrimiento de herramientas disponibles - Detecta y utiliza automáticamente todas las herramientas de los servidores conectados

Características del Agente React Native

El Agente MCP de React Native proporciona:

Gestión de Conversaciones - Historial de chat persistente con títulos generados por IA
Visualización de Mensajes Segmentados - Separación limpia de respuestas de texto y operaciones de herramientas
Ejecución de Herramientas en Tiempo Real - Retroalimentación visual con secciones de resultados plegables
Interfaz de Confirmación de Seguridad - Diálogos de confirmación nativos para operaciones de riesgo medio/alto
Soporte Multi-Modelo - Soporte para varios modelos de Gemini con cambio fácil
Multiplataforma - Funciona en plataformas iOS, Android y web
Material Design Moderno - Tema oscuro con animaciones suaves y retroalimentación háptica

🔐 Niveles de Riesgo

MCP Bridge implementa un sistema de niveles de riesgo opcional que proporciona control sobre los comportamientos de ejecución del servidor. Los niveles de riesgo ayudan a gestionar preocupaciones de seguridad y recursos al ejecutar operaciones potencialmente sensibles del servidor MCP.

Clasificación de Niveles de Riesgo

Nivel	Nombre	Descripción	Comportamiento
1	Bajo	Ejecución estándar	Ejecución directa sin confirmación
2	Medio	Requiere confirmación	El cliente debe confirmar la ejecución antes de procesar
3	Alto	Ejecución con Docker requerida	El servidor se ejecuta en un contenedor Docker aislado

Configuración de Niveles de Riesgo

Los niveles de riesgo son opcionales para compatibilidad hacia atrás. Puedes configurar los niveles de riesgo en tu 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"
      }
    }
  }
}

Flujos de Trabajo de Niveles de Riesgo

Riesgo Bajo (Nivel 1)

Ejecución estándar sin pasos adicionales
Adecuado para operaciones con preocupaciones mínimas de seguridad
Este es el comportamiento predeterminado cuando no se especifica un nivel de riesgo

Riesgo Medio (Nivel 2)

El cliente realiza una solicitud de ejecución de herramienta
El servidor responde con una solicitud de confirmación que contiene un ID de confirmación
El cliente debe realizar una solicitud de confirmación separada para continuar
Solo después de la confirmación, el servidor ejecuta la operación

Tanto el Agente MCP-Gemini en Python como el Agente de React Native manejan este flujo de confirmación automáticamente, solicitando la aprobación del usuario cuando sea necesario.

Riesgo Alto (Nivel 3)

El servidor se ejecuta automáticamente en un contenedor Docker aislado
Proporciona aislamiento ambiental para el proceso del servidor MCP
Requiere que Docker esté instalado y configurado correctamente

📋 Registro de Cambios

Últimas Actualizaciones

✅ Soporte del Administrador de Paquetes UV: Se corrigió el problema con la carga de servidores MCP basados en UV (Python). MCP Bridge ahora inicializa y se comunica correctamente con servidores MCP de Python que utilizan el administrador de paquetes UV, resolviendo problemas de compatibilidad anteriores con cadenas de herramientas basadas en UV.
📱 Agente MCP de React Native: Se agregó una aplicación móvil integral con:
- Soporte multiplataforma para iOS, Android y web
- Interfaz moderna de Material Design 3 con tema oscuro
- Gestión inteligente de conversaciones con títulos generados por IA
- Ejecución de herramientas en tiempo real con retroalimentación visual
- Flujos de confirmación de seguridad integrados
- Soporte para múltiples modelos de Gemini, incluidos los últimos lanzamientos
🔧 Ejecución de Herramientas Mejorada: Se mejoraron las capacidades de razonamiento de múltiples pasos en todos los clientes
🛡️ Mejoras de Seguridad: Se mejoraron los flujos de confirmación de niveles de riesgo con mejor experiencia de usuario
📊 Mejor Manejo de Errores: Mecanismos de manejo y recuperación de errores más robustos

🌟 Impacto Comunitario y Reconocimiento

MCP Bridge ha ganado reconocimiento dentro de las comunidades de IA y desarrollo, siendo destacado en investigación académica, análisis de seguridad de la industria, discurso profesional y publicaciones técnicas. Estos reconocimientos resaltan el valor práctico y el impacto en el mundo real de nuestra solución de proxy ligera y agnóstica de LLM.

Citado por este artículo: De Inyecciones de Prompts a Explotaciones de Protocolo: Amenazas en Flujos de Trabajo de Agentes de IA Impulsados por LLM - Un artículo de investigación que discute las implicaciones de seguridad en flujos de trabajo de agentes de IA impulsados por LLM

Informe de Investigación: Seguridad de MCP - Investigación de seguridad de Wiz que destaca a MCP Bridge como un ejemplo de trabajo académico en el ecosistema MCP

*[Publicación de LinkedIn por Vaibhava Lakshmi Ravideshik](https://www.linkedin.com/posts/vaibhava-lakshmi-ravideshik_aiintegration-modelcontextprotocol-llm-activity-7344581233097547777-IktU/) - Discusión de un instructor de LinkedIn Learning sobre las aplicaciones prácticas de MCP Bridge* Medium Technical Article

Desbloqueando aplicaciones agénticas con el Protocolo de Contexto de Modelo (MCP) para servicios financieros - Artículo de Medium que presenta el patrón de diseño de MCP Bridge para aplicaciones financieras

🚧 Consideraciones de implementación

🔒 Seguridad

Usa HTTPS en producción
Añade autenticación para operaciones sensibles
Aísla por red los servicios críticos

📊 Escalado

Usa balanceadores de carga
Agrupa servidores de alta demanda
Realiza seguimiento de métricas y presión de recursos

📱 Implementación móvil

Para la aplicación React Native:

Compila para producción usando npx expo build
Configura la implementación en la tienda de aplicaciones con EAS Build
Configura actualizaciones por aire con EAS Update

📊 Comparación con otros repositorios de MCP Bridge/Proxy

Característica	`ivanboring/mcp-rest`	`INQUIRELAB/mcp-bridge-api` (Este repositorio)	`SecretiveShell/MCP-Bridge`	`JoshuaRileyDev/mcp-api`	`rakesh-eltropy/mcp-client`	`bartolli/mcp-llm-bridge`
⚙️ Lenguaje principal	Node.js	Node.js (Bridge) + Python (Agente) ✨	Python	Node.js	Python	Python
🎯 Propósito principal	Envoltorio REST simple	Bridge REST independiente del LLM + Agente Gemini	Bridge OpenAI y REST con muchas funciones + Servidor MCP	API REST para servidores MCP + Ejemplo de interfaz de chat	Agente LangChain con herramientas MCP (REST/CLI)	Bridge LLM MCP <-> (compatible con OpenAI)
🔌 Conexión MCP	Solo SSE	STDIO (gestionado) + Docker (basado en riesgo) ✔️	STDIO, SSE, Docker	STDIO	STDIO (LangChain)	STDIO
🚀 Interfaz de API	REST básico	API REST unificada ✔️	Compatible con OpenAI, REST, Servidor MCP (SSE)	API REST + Swagger	API REST (streaming), CLI	CLI interactivo
✨ Características clave	Lista/llamada básica de herramientas	Multi-servidor, niveles de riesgo, confirmación de seguridad, ejecución Docker, agente Gemini, flexibilidad de configuración ✨	Compatible con OpenAI, muestreo, multi-transporte, autenticación, Docker/Helm, configuración flexible	Multi-servidor, normalización de nombres de herramientas, Swagger, interfaz de chat	Integración LangChain, REST/CLI, streaming	Traducción de protocolo bidireccional, herramienta de base de datos
🔧 Configuración	Argumentos de CLI	Archivo JSON + variables de entorno ✔️	Archivo JSON, URL HTTP, variables de entorno	Archivo JSON (búsqueda multi-ruta), variables de entorno	Archivo JSON	Objeto Python, variables de entorno
🧩 Integración LLM	Ninguna	Sí (agente Gemini dedicado con razonamiento multi-paso) ✨	Sí (punto final OpenAI)	Ninguna (solo API)	Sí (LangChain)	Sí (cliente OpenAI)
🏗️ Complejidad	Baja	Baja ✔️	Alta	Moderada	Moderada-alta	Moderada
🛡️ Características de seguridad	Ninguna	Niveles de riesgo (medio/alto) + flujo de confirmación + aislamiento Docker ✨	Autenticación básica (claves API), CORS	Ninguna	Ninguna	Ninguna
📦 Dependencias clave	`express`, `mcp-client`	`express`, `uuid` (Bridge, dependencia mínima); `requests`, `google-genai`, `rich` (Agente)	`fastapi`, `mcp`, `mcpx`	`express`, `@mcp/sdk`, `socket.io`	`fastapi`, `

Alcance de la licencia

El código original del laboratorio INQUIRE está licenciado bajo la Licencia No Comercial PolyForm 1.0.0. Los conjuntos de datos, figuras y documentación originales del laboratorio INQUIRE están licenciados bajo CC BY-NC 4.0. Consulta LICENCIA para conocer el alcance y los textos completos de las licencias. Los materiales de otros titulares de derechos conservan sus términos originales.