MCP Bridge API

MCP Bridge API

面向模型上下文协议服务的轻量级、与大模型无关的 RESTful 代理

图：React Native MCP Agent 界面，左侧显示包含工具执行结果的聊天屏幕，右侧显示 MCP Bridge 连接状态和 Gemini API 配置的设置屏幕

作者：
Arash Ahmadi、Sarah S. Sharif 和 Yaser M. Banad*
美国俄克拉荷马州诺曼市，俄克拉荷马大学电气与计算机工程学院
*通讯作者：[email protected]

如果您想在自己的工作中引用此研究项目，请引用我们的论文：

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

📋 目录

• 📚 简介
• 🏗️ 架构
• 💾 安装
• 🐍 Python MCP-Gemini Agent
• 📱 React Native MCP Agent
• ⚙️ 配置
• 🧪 API 用法
• 🔐 风险级别
• 🌟 社区影响与认可
• 📋 更新日志
• 🚧 部署注意事项
• 📊 与其他 MCP Bridge/代理仓库的比较
• 📝 许可证

📚 简介

MCP Bridge 是一个轻量、快速且与大模型无关的代理，可连接多个模型上下文协议（MCP）服务，并通过统一的 REST API 提供其功能。它让任何平台上的客户端都能利用 MCP 功能，不受进程执行限制。与 Anthropic 的官方 MCP SDK 不同，MCP Bridge 完全独立，旨在与任何大模型后端配合使用，因此能够适应不同部署需求，具备模块化特性并面向未来。它还提供可选的基于风险的执行级别，支持从标准执行到确认工作流和 Docker 隔离等精细化安全控制，同时保持与标准 MCP 客户端的向后兼容性。

除了服务器端基础设施之外，项目还提供了两种不同的智能客户端实现：

1. Python MCP-Gemini Agent - 面向桌面环境的命令行 Python 客户端
2. React Native MCP Agent - 现代化的跨平台移动应用

这两种客户端都通过由大模型驱动的智能界面，支持使用自然语言与 MCP 工具交互，并具备针对复杂操作的多步推理、安全确认工作流处理以及可配置的显示选项，从而提升易用性。MCP Bridge 灵活多样的服务器端功能与这些智能客户端界面相结合，构成了一个强大的生态系统，可用于开发复杂的大模型应用。

⚠️ 问题

• 许多 MCP 服务使用 STDIO 传输，需要在本地执行进程
• 边缘设备、移动设备、网页浏览器和其他平台无法高效运行 npm 或 Python MCP 服务
• 在资源受限的环境中，直接连接 MCP 服务并不实用
• 多个相互隔离的客户端连接到同一批服务会造成冗余并增加资源使用量
• 直接使用 MCP 工具需要了解特定工具的格式和要求

🏗️ 架构

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

💾 安装

📦 前置条件

• MCP Bridge 需要 Node.js 18+
• Python MCP-Gemini Agent 需要 Python 3.8+
• 移动应用需要 React Native 开发环境

🚀 快速设置

MCP Bridge

# Install dependencies
npm install express cors morgan uuid

# Start the server
node mcp-bridge.js

Python MCP-Gemini Agent

# Install dependencies
pip install google-generativeai requests rich

# Start the agent
python llm_test.py

React Native MCP Agent

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

# Install dependencies
npm install

# Start the development server
npx expo start

🐍 Python MCP-Gemini Agent

Python MCP-Gemini Agent 是一个命令行客户端，可连接到 MCP Bridge，并使用 Google 的 Gemini 大模型处理用户请求和执行 MCP 工具命令。它专为桌面环境和开发工作流设计。

主要功能

1. 多步推理 - 支持按顺序调用工具，以执行复杂操作
2. 安全确认流程 - 集成处理中等和高风险操作的机制
3. 灵活的 JSON 显示 - 控制 JSON 输出的详细程度，提升可读性
4. 可配置的连接 - 使用自定义 URL 和端口连接到任意 MCP Bridge 实例
5. 发现可用工具 - 自动检测并使用已连接服务中的所有工具

Python Agent 配置

Python MCP-Gemini Agent 支持多个命令行选项：

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)

Python Agent 使用示例

# 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

📱 React Native MCP Agent

React Native MCP Agent 是一款现代化的跨平台移动应用，通过简洁易用的界面提供直观的 MCP 工具访问体验。它基于 Expo 和 React Native Paper 构建，提供深色主题的 Material Design 3 界面，并针对 iOS 和 Android 平台进行了优化。

主要功能

• 跨平台兼容性：可在 iOS、Android 和 Web 平台运行
• 直观的聊天界面：通过分段的消息显示进行自然语言交互
• 实时工具执行：通过可折叠的结果区域，为 MCP 工具调用提供可视化反馈
• 对话管理：持久保存对话历史，并由 AI 生成标题
• 现代化 UI/UX：深色主题，搭配玻璃拟态效果和流畅动画
• 全面的设置：轻松配置 MCP Bridge 连接和 Gemini API 设置
• 安全集成：内置对 MCP Bridge 风险等级确认工作流的支持
• 多模型支持：兼容多种 Gemini 模型，包括最新的 2.5 Flash Preview

开始使用 React Native 应用

1. 配置 MCP Bridge：在“设置”选项卡中设置 MCP Bridge 服务 URL
2. 添加 Gemini API 密钥：输入 Google Gemini API 密钥以启用 AI 功能
3. 选择模型：从可用的 Gemini 模型中进行选择，包括最新发布的模型
4. 开始聊天：使用 MCP 工具开始自然语言对话

应用会自动发现可用的 MCP 工具，并针对复杂的多步操作提供上下文辅助。

⚙️ 配置

MCP Bridge 配置

MCP Bridge 通过项目根目录中名为 mcp_config.json 的 JSON 文件进行配置。以下是基本 MCP 配置示例：

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

🧪 API 用法

MCP Bridge 提供简洁直观的 REST API，用于与已连接的服务交互。以下是可用端点的说明：

📋 通用端点

端点	方法	描述
/servers	GET	列出所有已连接的 MCP 服务
/servers	POST	启动新的 MCP 服务
/servers/{serverId}	DELETE	停止并移除 MCP 服务
/health	GET	获取 MCP Bridge 的健康状态
/confirmations/{confirmationId}	POST	确认执行中等风险级别的请求

📌 服务专属端点

端点	方法	描述
/servers/{serverId}/tools	GET	列出指定服务的所有工具
/servers/{serverId}/tools/{toolName}	POST	执行指定工具
/servers/{serverId}/resources	GET	列出所有资源
/servers/{serverId}/resources/{resourceUri}	GET	获取指定资源的内容
/servers/{serverId}/prompts	GET	列出所有提示词
/servers/{serverId}/prompts/{promptName}	POST	使用参数执行提示词

🧪 请求示例

📂 读取目录（文件系统）

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

{
  "path": "."
}

🧪 客户端功能

Python Agent 功能

Python MCP-Gemini Agent 提供：

1. 多步推理 - 支持按顺序调用工具以完成复杂操作
2. 安全确认流程 - 集成处理中风险和高风险操作
3. 灵活的 JSON 显示 - 控制 JSON 输出的详细程度，提高可读性
4. 可配置的连接 - 使用自定义 URL 和端口连接到任何 MCP Bridge 实例
5. 发现可用工具 - 自动检测并使用已连接服务中的所有工具

React Native Agent 功能

React Native MCP Agent 提供：

1. 对话管理 - 持久化聊天记录，并使用 AI 生成标题
2. 分段消息显示 - 清晰区分文本回复和工具操作
3. 实时工具执行 - 通过可折叠的结果区域提供视觉反馈
4. 安全确认界面 - 针对中风险／高风险操作的原生确认对话框
5. 多模型支持 - 支持多种 Gemini 模型，并可轻松切换
6. 跨平台 - 支持 iOS、Android 和 Web 平台
7. 现代 Material Design - 深色主题，配合流畅动画和触觉反馈

🔐 风险级别

MCP Bridge 实现了一个可选的风险级别系统，用于控制服务端的执行行为。执行可能涉及敏感信息的 MCP 服务操作时，风险级别有助于管理安全和资源方面的注意事项。

风险级别分类

级别	名称	描述	行为
1	低	标准执行	无需确认，直接执行
2	中	需要确认	客户端必须在处理前确认执行
3	高	必须使用 Docker 执行	服务在隔离的 Docker 容器中运行

配置风险级别

风险级别为可选项，以保持向后兼容。你可以在 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"
      }
    }
  }
}

风险级别工作流

低风险（级别 1）

• 无需额外步骤即可标准执行
• 适用于安全方面顾虑极少的操作
• 未指定风险级别时，默认采用此行为

中风险（级别 2）

1. 客户端发起工具执行请求
2. 服务端返回包含确认 ID 的确认请求
3. 客户端必须单独发起确认请求才能继续
4. 只有确认后，服务端才会执行操作

Python MCP-Gemini Agent 和 React Native Agent 均会自动处理此确认流程，并在需要时提示用户批准。

高风险（级别 3）

• 服务端自动在隔离的 Docker 容器中运行
• 为 MCP 服务进程提供环境隔离
• 需要安装并正确配置 Docker

📋 更新日志

最新更新

• ✅ 支持 UV 包管理器：修复了无法加载基于 UV 的（Python）MCP 服务的问题。MCP Bridge 现在可以正确初始化并与使用 UV 包管理器的 Python MCP 服务通信，解决了先前与基于 UV 的工具链的兼容性问题。

• 📱 React Native MCP Agent：新增了一款功能全面的移动应用，具备以下特性：

  • 支持 iOS、Android 和 Web 平台
  • 采用 Material Design 3 的现代界面，支持深色主题
  • 智能管理对话，并使用 AI 生成标题
  • 实时执行工具并提供视觉反馈
  • 内置安全确认工作流
  • 支持多个 Gemini 模型，包括最新版本

• 🔧 增强工具执行：提升了所有客户端的多步推理能力

• 🛡️ 安全改进：优化了风险级别确认流程，提升用户体验

• 📊 改进错误处理：采用更稳健的错误处理和恢复机制

🌟 社区影响力与认可

MCP Bridge 已获得 AI 和开发者社区的认可，出现在学术研究、行业安全分析、专业讨论和技术出版物中。这些认可彰显了我们轻量级、与 LLM 无关的代理解决方案的实用价值和实际影响。

本文引用：From Prompt Injections to Protocol Exploits: Threats in LLM-Powered AI Agents Workflows - 一篇探讨大模型驱动的 AI Agent 工作流安全影响的研究论文

研究简报：MCP Security - Wiz 的安全研究将 MCP Bridge 列为 MCP 生态系统中的学术研究案例

Vaibhava Lakshmi Ravideshik 发布的 LinkedIn 帖子 - 一位 LinkedIn Learning 讲师讨论 MCP Bridge 的实际应用

借助模型上下文协议（MCP）为金融服务解锁 Agentic 应用 - Medium 文章介绍了 MCP Bridge 在金融应用中的设计模式

🚧 部署注意事项

🔒 安全

• 在生产环境中使用 HTTPS
• 为敏感操作添加身份验证
• 隔离关键服务所在的网络

📊 扩展

• 使用负载均衡器
• 对高需求服务进行池化
• 跟踪指标和资源压力

📱 移动端部署

对于 React Native 应用：

• 使用 npx expo build 构建生产版本
• 使用 EAS Build 配置应用商店部署
• 使用 EAS Update 设置无线更新

📊 与其他 MCP Bridge/代理仓库的比较

特性	ivanboring/mcp-rest	INQUIRELAB/mcp-bridge-api（此仓库）	SecretiveShell/MCP-Bridge	JoshuaRileyDev/mcp-api	rakesh-eltropy/mcp-client	bartolli/mcp-llm-bridge
⚙️ 主要语言	Node.js	Node.js（Bridge）+ Python（Agent）✨	Python	Node.js	Python	Python
🎯 主要用途	简单的 REST 封装	与大模型无关的 REST Bridge + Gemini Agent	功能丰富的 OpenAI 与 REST Bridge + MCP 服务	MCP 服务的 REST API + 聊天 UI 示例	使用 MCP 工具的 LangChain Agent（REST/CLI）	MCP <-> LLM Bridge（兼容 OpenAI）
🔌 MCP 连接方式	仅 SSE	STDIO（托管）+ Docker（基于风险）✔️	STDIO、SSE、Docker	STDIO	STDIO（LangChain）	STDIO
🚀 API 接口	基本 REST	统一 REST API ✔️	兼容 OpenAI、REST、MCP 服务（SSE）	REST API + Swagger	REST API（流式传输）、CLI	交互式 CLI
✨ 主要功能	基本工具列表/调用	多服务、风险等级、安全确认、Docker 执行、Gemini Agent、灵活配置✨	兼容 OpenAI、Sampling、多传输方式、身份验证、Docker/Helm、灵活配置	多服务、工具名称规范化、Swagger、聊天 UI	LangChain 集成、REST/CLI、流式传输	双向协议转换、数据库工具
🔧 配置方式	CLI 参数	JSON 文件 + 环境变量✔️	JSON 文件、HTTP URL、环境变量	JSON 文件（多路径搜索）、环境变量	JSON 文件	Python 对象、环境变量
🧩 大模型集成	无	有（专用 Gemini Agent，支持多步推理）✨	有（OpenAI 端点）	无（仅 API）	有（LangChain）	有（OpenAI 客户端）
🏗️ 复杂度	低	低✔️	高	中等	中高	中等
🛡️ 安全功能	无	风险等级（中/高）+ 确认流程 + Docker 隔离✨	基本身份验证（API 密钥）、CORS	无	无	无
📦 主要依赖项	express、mcp-client	express、uuid（Bridge，最少依赖）；requests、google-genai、rich（Agent）	fastapi、mcp、mcpx	express、@mcp/sdk、socket.io	fastapi、`

许可范围

INQUIRE Lab 的原始代码采用 PolyForm Noncommercial License 1.0.0 许可。INQUIRE Lab 的原始数据集、图表和文档采用 CC BY-NC 4.0 许可。许可范围和完整许可文本请参见 LICENSE。其他权利持有者的材料保留其原始条款。