MCP Bridge API

A Lightweight, LLM-Agnostic RESTful Proxy for Model Context Protocol Servers

Figure: The React Native MCP Agent interface showing the chat screen with tool execution results (left) and the settings screen with MCP Bridge connection status and Gemini API configuration (right)

Authors:
Arash Ahmadi, Sarah S. Sharif, and Yaser M. Banad
School of Electrical, and Computer Engineering, University of Oklahoma, Oklahoma, United States
Corresponding author:bana@ou.edu

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

- 📚 Introduction
- 🏗️ Architecture
- 💾 Installation
- 🐍 Python MCP-Gemini Agent
- 📱 React Native MCP Agent
- ⚙️ Configuration
- 🧪 API Usage
- 🔐 Risk Levels
- 🌟 Community Impact and Recognition
- 📋 Changelog
- 🚧 Deployment Considerations
- 📊 Comparison with Other MCP Bridge/Proxy Repositories
- 📝 License

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

# Install dependencies npm install express cors morgan uuid # Start the server node mcp-bridge.js

# Install dependencies pip install google-generativeai requests rich # Start the agent python llm_test.py

# Navigate to the React Native app directory cd reactnative-gamini-mcp-agent # Install dependencies npm install # Start the development server npx expo start

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)

# 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

The React Native MCP Agent is a modern, cross-platform mobile application that provides intuitive access to MCP tools through a clean, user-friendly interface. Built with Expo and React Native Paper, it offers a dark-themed, Material Design 3 interface optimized for both iOS and Android platforms.

- Cross-Platform Compatibility: Runs on iOS, Android, and web platforms
- Intuitive Chat Interface: Natural language interaction with segmented message display
- Real-Time Tool Execution: Visual feedback for MCP tool calls with collapsible result sections
- Conversation Management: Persistent conversation history with AI-generated titles
- Modern UI/UX: Dark theme with glassmorphism effects and smooth animations
- Comprehensive Settings: Easy configuration of MCP Bridge connections and Gemini API settings
- Security Integration: Built-in support for MCP Bridge's risk-level confirmation workflows
- Multi-Model Support: Compatible with various Gemini models including the latest 2.5 Flash Preview

Getting Started with the React Native app

The app automatically discovers available MCP tools and provides contextual assistance for complex multi-step operations.

MCP Bridge is configured through a JSON file namedmcp_config.jsonin the project root. This is an example of a basic MCP config:

{ "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 } } }

MCP Bridge exposes a clean and intuitive REST API for interacting with connected servers. Here's a breakdown of available endpoints:

POST /servers/filesystem/tools/list_directory Content-Type: application/json { "path": "." }

- Multi-step reasoning- Supports sequenced tool calls for complex operations
- Security confirmation flow- Integrated handling for medium and high risk operations
- Flexible JSON display- Control the verbosity of JSON outputs for better readability
- Configurable connection- Connect to any MCP Bridge instance with custom URL and port
- Discovery of available tools- Automatically detects and uses all tools from connected servers
- Conversation Management- Persistent chat history with AI-generated titles
- Segmented Message Display- Clean separation of text responses and tool operations
- Real-time Tool Execution- Visual feedback with collapsible result sections
- Security Confirmation UI- Native confirmation dialogs for medium/high risk operations
- Multi-Model Support- Support for various Gemini models with easy switching
- Cross-Platform- Works on iOS, Android, and web platforms
- Modern Material Design- Dark theme with smooth animations and haptic feedback

MCP Bridge implements an optional risk level system that provides control over server execution behaviors. Risk levels help manage security and resource concerns when executing potentially sensitive MCP server operations.

Risk levels are optional for backward compatibility. You can configure risk levels in yourmcp_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" } } } }

- Standard execution without additional steps
- Suitable for operations with minimal security concerns
- This is the default behavior when no risk level is specified
- Client makes a tool execution request
- Server responds with a confirmation request containing a confirmation ID
- Client must make a separate confirmation request to proceed
- Only after confirmation does the server execute the operation

Both the Python MCP-Gemini Agent and React Native Agent handle this confirmation flow automatically, prompting the user for approval when needed.

- Server automatically runs in an isolated Docker container
- Provides environmental isolation for the MCP server process
- Requires Docker to be installed and properly configured

-

✅ UV Package Manager Support: Fixed the issue with loading UV-based (Python) MCP servers. MCP Bridge now properly initializes and communicates with Python MCP servers that use the UV package manager, resolving previous compatibility issues with UV-based toolchains.

📱 React Native MCP Agent: Added a comprehensive mobile application with:

- Cross-platform support for iOS, Android, and web
- Modern Material Design 3 interface with dark theming
- Intelligent conversation management with AI-generated titles
- Real-time tool execution with visual feedback
- Built-in security confirmation workflows
- Support for multiple Gemini models including latest releases

🔧 Enhanced Tool Execution: Improved multi-step reasoning capabilities across all clients

🛡️ Security Improvements: Enhanced risk-level confirmation flows with better user experience

📊 Better Error Handling: More robust error handling and recovery mechanisms

MCP Bridge has gained recognition within the AI and development communities, being featured in academic research, industry security analyses, professional discourse, and technical publications. These acknowledgments highlight the practical value and real-world impact of our lightweight, LLM-agnostic proxy solution.

Cited by this paper: From Prompt Injections to Protocol Exploits: Threats in LLM-Powered AI Agents Workflows- A research paper discussing security implications in LLM-powered AI agent workflows

Research Briefing: MCP Security- Wiz security research highlighting MCP Bridge as an example of academic work in the MCP ecosystem

LinkedIn Post by Vaibhava Lakshmi Ravideshik- A LinkedIn Learning Instructor discussion about MCP Bridge's practical applications

Unlocking Agentic Apps with the Model Context Protocol (MCP) For Financial Services- Medium article featuring MCP Bridge's design pattern for financial applications

Tool platform by IBM to build, test and deploy tools for any data source