使用说明

MCP网关

管理多个MCP（模型上下文协议）服务器的智能中介系统。网关同时充当MCP客户端（南行）和MCP服务器（北行），为AI代理提供细粒度的工具组合。

什么是MCP网关？

MCP网关允许您：

板载多台MCP服务器 通过STDIO或流式HTTP传输
自动发现 每个服务器上的所有可用工具
创建自定义MCP端点 暴露不同子集的工具
路由工具调用 自动转到正确的后端服务器

示例：连接到文件系统MCP服务器和时间MCP服务器，然后创建单独的端点——一个用于具有只读文件工具的代理a，另一个用于仅具有时间工具的代理B。

主要特点

南向一体化：连接到多个MCP服务器（STDIO和流式HTTP）
北向暴露：使用自定义工具选择创建多个MCP服务器实例
动态配置：通过web UI或API随时修改工具选择
工具发现：自动对已登录服务器中的所有工具进行编目
标签系统：使用标签组织工具和实例
REST API：用于程序控制的全面API
健康监测：自动重新连接和健康检查
Web用户界面：现代基于React的管理界面

技术栈

后端

Python 3.11+ 使用FastMCP 2.0+
快速API 用于REST API
PostgreSQL 15+ （必填-不支持SQLite）
SQLAlchemy 2.0+ 支持异步
蒸馏器 用于数据库迁移

前端

反应19 使用TypeScript
尾风CSS 4
维特用于构建工具

快速开始

🐳 Docker（推荐）

在一分钟内起床并跑步：

# Start all services
docker compose up -d

# View logs
docker compose logs -f

就是这样！ 访问应用程序：

后端API: http://localhost:8000
前端用户界面: http://localhost:3000
API文件: http://localhost:8000/docs

服务包括：

PostgreSQL 15数据库
后端API服务器（FastAPI）
前端web UI（React）

手动安装

对于没有Docker的开发，请参阅中的详细设置指南 docs/QUICKSTART_MODERN.md.

快速版本:

# 1. Install PostgreSQL 15+ and create database
# 2. Install Python dependencies
pip install -e .

# 3. Configure database (create .env file)
DATABASE_URL=postgresql+asyncpg://postgres:password@localhost:5432/mcp_gateway

# 4. Run migrations and start
alembic upgrade head
python -m app.main

后端运行速度为http://localhost:8000

使用示例

板载MCP服务器（STDIO-系统已安装）

curl -X POST http://localhost:8000/api/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Time Server",
    "description": "MCP server for time operations",
    "transport_type": "stdio",
    "installation_type": "system",
    "connection_config": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-time"]
    }
  }'

板载MCP服务器（STDIO-来自GitHub）

网关可以从GitHub存储库自动克隆和安装MCP服务器：

curl -X POST http://localhost:8000/api/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Custom Server",
    "description": "Custom MCP server from GitHub",
    "transport_type": "stdio",
    "installation_type": "git",
    "git_repo_url": "https://github.com/username/my-mcp-server",
    "git_branch": "main",
    "connection_config": {
      "command": "node",
      "args": ["index.js"]
    }
  }'

网关将：

将存储库克隆到 /app/mcp-servers/{server-id}
自动检测项目类型（Node.js、Python等）
运行安装命令(npm install, pip install等等）
如果未在中指定，则检测入口点 connection_config
存储提交SHA和安装元数据

git安装的可选字段：

install_command：覆盖自动检测到的安装命令（例如。， "npm ci")
setup_command：附加构建/设置命令（例如。， "npm run build")
git_branch：要克隆的分支（默认值： "main")

板载MCP服务器（可流式HTTP）

curl -X POST http://localhost:8000/api/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Remote Server",
    "transport_type": "streamable_http",
    "connection_config": {
      "url": "http://your-server.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }'

创建北向实例

# First, get available tools
curl http://localhost:8000/api/tools

# Create instance with selected tools
curl -X POST http://localhost:8000/api/instances \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agent Tools",
    "description": "Custom tool selection for my AI agent",
    "tool_ids": ["tool-id-1", "tool-id-2"]
  }'

将AI代理连接到实例

from fastmcp import Client

# Connect to your instance endpoint
client = Client("http://localhost:8000/mcp/instances/{instance-id}")

async with client:
    # List available tools
    tools = await client.list_tools()
    print(f"Available tools: {[t.name for t in tools]}")

    # Call a tool
    result = await client.call_tool("get_time", {})
    print(f"Result: {result}")

API文档

交互式API文档：

Swagger用户界面: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

关键终点

服务器

POST /api/servers -板载MCP服务器
GET /api/servers -列出所有服务器
GET /api/servers/{id} -获取服务器详细信息
DELETE /api/servers/{id} -删除服务器
POST /api/servers/{id}/connect -手动连接
POST /api/servers/{id}/disconnect -手动断开连接

实例

POST /api/instances -创建实例
GET /api/instances -列出实例
GET /api/instances/{id} -获取实例
PUT /api/instances/{id} -更新实例
DELETE /api/instances/{id} -删除实例

工具

GET /api/tools -列出所有发现的工具
GET /api/tools/{id} -获取工具详细信息

MCP协议

POST /mcp/instances/{id} -MCP JSON-RPC端点（此处连接代理）

建筑

三层设计

┌─────────────────────────────────────────┐
│   Frontend (React 19 + TailwindCSS 4)  │
│   Web UI for management                 │
└─────────────┬───────────────────────────┘
              │ REST API
              ▼
┌─────────────────────────────────────────┐
│   FastAPI Backend (FastMCP 2.0+)       │
│   Gateway Logic & Configuration         │
├─────────────────────────────────────────┤
│   Northbound Manager (MCP Server)      │
│   - Dynamic instance creation           │
│   - Tool selection & composition        │
│   - MCP protocol endpoints              │
├─────────────────────────────────────────┤
│   Southbound Manager (MCP Client)      │
│   - STDIO transport (local)             │
│   - Streamable HTTP (remote)            │
│   - Tool discovery & cataloging         │
│   - Connection lifecycle management     │
└─────────────┬───────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────┐
│   MCP Servers (Multiple)                │
│   - Time, Filesystem, Custom, etc.      │
└─────────────────────────────────────────┘

关键组件

南行经理：管理MCP客户端连接、工具发现和调用代理
北行经理：使用自定义工具选择创建和管理MCP服务器实例
工具注册表：使用模式维护所有可用工具的目录
配置引擎：处理实例配置和实时更新

发展

运行测试

pytest

代码格式化

# Auto-format code
black .

# Run linter
ruff check .

# Type checking
mypy app/

数据库迁移

# Create new migration
alembic revision --autogenerate -m "Description"

# Apply migrations
alembic upgrade head

# Rollback one migration
alembic downgrade -1

文档

有关详细指南和技术文档：

docs/QUICKSTART_MODERN.md -带示例的全面设置指南
代理商.md -AI代理持久内存和代码模式（主要参考）
PROMPT.md -完整的项目要求和规范

项目结构

mcp_gateway/
├── app/
│   ├── api/              # FastAPI routes and schemas
│   │   ├── routes/       # API endpoint handlers
│   │   └── schemas/      # Pydantic models
│   ├── core/             # Core configuration and utilities
│   ├── managers/         # Business logic managers
│   │   ├── southbound.py # MCP client connections
│   │   ├── northbound.py # MCP server instances
│   │   └── tool_registry.py # Tool catalog
│   ├── models/           # SQLAlchemy database models
│   ├── transports/       # MCP transport implementations
│   ├── utils/            # Utility functions
│   └── main.py           # FastAPI application entry point
├── alembic/              # Database migrations
├── frontend/             # React web UI
│   └── mcp-gateway-ui/
├── tests/                # Test suite
├── docs/                 # Documentation
├── docker-compose.yml    # Docker deployment
├── pyproject.toml        # Python dependencies and config
└── README.md             # This file

数据库要求

PostgreSQL 15+是必需的。 SQLite不受支持，原因如下：

嵌套交易要求
异步连接池需求
并发MCP服务器连接管理

使用附带的Docker Compose设置轻松部署PostgreSQL。

性能与安全

绩效目标

API响应时间：＜100ms（不包括工具调用）
工具代理开销：<50ms
支持100+并发代理连接
每分钟处理1000+次工具调用

安全最佳实践

在静止时加密机密（API密钥、令牌）
在生产环境中使用HTTPS
为web UI配置CORS
对API端点实施速率限制
验证流式HTTP的Origin标头（防止DNS重新绑定）

支持

对于问题和疑问：

查看中的文档 docs/
查看API文档，网址：http://localhost:8000/docs
在GitHub上打开一个问题

许可证

麻省理工学院

基于FastMCP 2.0+构建•React 19•TailwindCSS 4•PostgreSQL 15