MCP Access Point

MCP 接入点

MCP Access Point 是一款轻量级协议转换网关工具，旨在搭建传统 HTTP 服务与 MCP（模型上下文协议）客户端之间的通信桥梁。它使 MCP 客户端无需修改服务器端接口，就能直接与现有的 HTTP 服务交互。

简介

本项目基于 Pingora 构建。Pingora 是一款超高性能网关代理库，可支持大规模请求代理服务。Cloudflare 平台的核心流量服务便是使用 Pingora 构建的，多年来持续为互联网处理每秒超过 4,000 万个请求。它已成为支撑 Cloudflare 平台相当大比例流量的技术基石。

HTTP 转 MCP

此模式允许 Cursor Desktop 等客户端通过 SSE 与远程 HTTP 服务通信，即使这些服务本身不支持 SSE 协议。

• 示例配置包含两个服务：
  • 服务 1 在本地 127.0.0.1:8090 运行
  • 服务 2 在远程 api.example.com 运行
• 通过 MCP Access Point，无需修改代码即可将这两个服务转换为 MCP 服务。
• 客户端通过 MCP 协议与 Service 1 和 Service 2 通信。MCP Access Point 会自动识别 MCP 请求，并将其转发到相应的后端服务。

graph LR
   A["Cursor Desktop"] <--> |SSE| B["MCP Access Point"]
   A2["Other Desktop"] <--> |Streamable Http| B["MCP Access Point"]
   B <--> |http 127.0.0.1:8090| C1["Existing API Server"]
   B <--> |https//api.example.com| C2["Existing API Server"]
  
   style A2 fill:#ffe6f9,stroke:#333,color:black,stroke-width:2px
   style A fill:#ffe6f9,stroke:#333,color:black,stroke-width:2px
   style B fill:#e6e6af,stroke:#333,color:black,stroke-width:2px
   style C1 fill:#e6ffe6,stroke:#333,color:black,stroke-width:2px
   style C2 fill:#e6ffd6,stroke:#333,color:black,stroke-width:2px

传输类型（规范）

目前支持 SSE 和 Streamable HTTP 协议：

• ✅ Streamable HTTP（无状态）2025-03-26

  • 所有服务：ip:port/mcp
  • 单个服务：ip:port/api/{service_id}/mcp

• ✅ SSE 2024-11-05

  • 所有服务：ip:port/sse
  • 单个服务：ip:port/api/{service_id}/sse

SSE 使用 IP:PORT/sse Streamable HTTP 使用 IP:PORT/mcp

支持的 MCP 客户端

• ✅ MCP Inspector
• ✅ Cursor Desktop
• ✅ Windsurf
• ✅ VS Code
• ✅ Trae

核心功能

• 协议转换：在 HTTP 和 MCP 协议之间无缝转换
• 无侵入式集成：与现有 HTTP 服务完全兼容
• 赋能客户端：使 MCP 客户端能够直接调用标准 HTTP 服务
• 轻量级代理：采用精简架构，实现高效的协议转换
• 多租户：为每个租户提供独立的配置和端点
• 运行时配置管理：无需重启服务即可动态更新配置
• 管理 API：用于实时配置管理的 RESTful API

快速开始

安装

# Install from source
git clone https://github.com/sxhxliang/mcp-access-point.git
cd mcp-access-point
cargo run -- -c config.yaml

# Use inspector for debugging (start service first)
npx @modelcontextprotocol/inspector node build/index.js
# Access http://127.0.0.1:6274/
# Select "SSE" and enter 0.0.0.0:8080/sse, then click connect
# or select "Streamable HTTP" and enter 0.0.0.0:8080/mcp

多租户支持

MCP Access Gateway 支持多租户，每个租户可以配置多个 MCP 服务，并通过以下地址访问：

• /api/{mcp-service-id}/sse（用于 SSE）
• /api/{mcp-service-id}/mcp（用于 Streamable HTTP）

配置示例：

# config.yaml example (supports multiple services)

mcps:
  - id: service-1 # Access via /api/service-1/sse or /api/service-1/mcp
    ... # Service configuration
  - id: service-2 # Access via /api/service-2/sse or /api/service-2/mcp
    ... # Service configuration
  - id: service-3 # Access via /api/service-3/sse or /api/service-3/mcp
    ... # Service configuration

如需同时访问所有服务，请使用：

• 0.0.0.0:8080/mcp（Streamable HTTP）
• 0.0.0.0:8080/sse（SSE）

配置详情

1. -c config.yaml
   • -c（或 --config）用于指定配置文件路径（config.yaml）。
   • 此文件定义 MCP Access Point 将代理和转换的 API。

config.yaml 示例

配置文件支持多租户，可为每个 MCP 服务独立配置上游服务和路由规则。主要配置项包括：

1. mcps - MCP 服务列表

   • id：用于生成访问路径的唯一服务标识符
   • upstream_id：关联的上游服务 ID
   • path：OpenAPI 规范文件路径。支持本地文件（例如 config/openapi.json）和远程 HTTP/HTTPS URL（例如 https://petstore.swagger.io/v2/swagger.json）。支持 JSON 和 YAML 格式。
   • routes：自定义路由配置（可选）
   • upstream：上游服务专属配置（可选）

2. upstreams - 上游服务配置

   • id：上游服务 ID
   • nodes：后端节点地址和权重
   • type：负载均衡算法（roundrobin/random/ip_hash）
   • scheme：上游协议（http/https）
   • pass_host：HTTP Host 请求头处理方式
   • upstream_host：覆盖 Host 请求头的值

完整配置示例：

# config.yaml example (supports multiple services)
mcps:
  - id: service-1 # Unique identifier, accessible via /api/service-1/sse or /api/service-1/mcp
    upstream_id: 1
    path: config/openapi_for_demo_patch1.json # Local OpenAPI spec path

  - id: service-2 # Unique identifier
    upstream_id: 2
    path: https://petstore.swagger.io/v2/swagger.json # Remote OpenAPI spec

  - id: service-3 
    upstream_id: 3
    routes: # Custom routing
      - id: 1
        operation_id: get_weather
        uri: /points/{latitude},{longitude}
        method: GET
        meta:
          name: Get Weather
          description: Retrieve weather information by coordinates
          inputSchema: # Optional input validation
            type: object
            required:
              - latitude
              - longitude
            properties:
              latitude:
                type: number
                minimum: -90
                maximum: 90
              longitude:
                type: number
                minimum: -180
                maximum: 180

upstreams: # Required upstream configuration
  - id: 1
    headers: # Headers to send to upstream service
      X-API-Key: "12345-abcdef"        # API key
      Authorization: "Bearer token123" # Bearer token
      User-Agent: "MyApp/1.0"          # User agent
      Accept: "application/json"       # Accept header
    nodes: # Backend nodes (IP or domain)
      "127.0.0.1:8090": 1 # Format: address:weight

  - id: 2 
    nodes:
      "127.0.0.1:8091": 1

  - id: 3 
    nodes:
      "api.weather.gov": 1
    type: roundrobin # Load balancing algorithm
    scheme: https # Protocol
    pass_host: rewrite # Host header handling
    upstream_host: api.weather.gov # Override Host

使用配置文件运行 MCP Access Gateway：

cargo run -- -c config.yaml

通过 Docker 运行

本地运行以快速开始

# Note: Replace /path/to/your/config.yaml with actual path
docker run -d --name mcp-access-point --rm \
  -p 8080:8080 \
  -e port=8080 \
  -v /path/to/your/config.yaml:/app/config/config.yaml \
  ghcr.io/sxhxliang/mcp-access-point:main

构建 Docker 镜像（可选）

• 安装 docker
• 克隆仓库并构建镜像

# Clone repository
git clone https://github.com/sxhxliang/mcp-access-point.git
cd mcp-access-point

# Build image
docker build -t liangshihua/mcp-access-point:latest .

• 运行 Docker 容器

# Using environment variables (service running on host)
# Note: Replace /path/to/your/config.yaml with actual path

docker run -d --name mcp-access-point --rm \
  -p 8080:8080 \
  -e port=8080 \
  -v /path/to/your/config.yaml:/app/config/config.yaml \
  liangshihua/mcp-access-point:latest

环境变量

• port：MCP Access Point 监听端口（默认：8080）

典型用例

• 渐进式架构迁移：促进从 HTTP 到 MCP 的逐步过渡
• 混合架构支持：在 MCP 生态系统中复用现有 HTTP 基础设施
• 协议兼容性：构建同时支持两种协议的混合系统

示例场景：
当基于 MCP 的 AI 客户端需要与旧版 HTTP 微服务交互时，MCP Access Gateway 充当中间件层，实现无缝协议转换。

特别感谢 @limcheekin 撰写了包含实践示例的文章：https://limcheekin.medium.com/building-your-first-no-code-mcp-server-the-fabric-integration-story-90da58cdbe1f

运行时配置管理

MCP Access Point 现已支持通过 RESTful Admin API 动态管理配置，无需重启服务即可更新配置。

Admin API 功能

• 实时配置更新：即时修改上游服务、服务、路由及其他资源
• 依赖项验证：变更前自动验证资源依赖关系
• 批量操作：以原子方式执行多项配置变更
• 配置验证：提供试运行模式，在应用变更前进行验证
• 资源统计：监控并跟踪配置状态

Admin API 配置

在 config.yaml 中添加以下内容以启用 Admin API：

access_point:
  admin:
    address: "127.0.0.1:8081"  # Admin API listening address
    api_key: "your-api-key"    # Optional API key for authentication

Admin API 端点

资源管理

• GET /admin/resources - 获取资源摘要和统计信息
• GET /admin/resources/{type} - 列出指定类型的所有资源
• GET /admin/resources/{type}/{id} - 获取指定资源
• POST /admin/resources/{type}/{id} - 创建新资源
• PUT /admin/resources/{type}/{id} - 更新现有资源
• DELETE /admin/resources/{type}/{id} - 删除资源

高级操作

• POST /admin/validate/{type}/{id} - 验证资源配置
• POST /admin/batch - 执行批量操作
• POST /admin/reload/{type} - 重新加载指定类型的资源
• POST /admin/reload/config - 从文件重新加载完整配置（默认为 config.yaml）。可选 JSON 请求体：{ "config_path": "path/to/config.yaml" }

支持的资源类型

• upstreams - 后端服务配置
• services - 服务定义
• routes - 路由规则
• global_rules - 全局插件规则
• mcp_services - MCP 服务配置
• ssls - SSL 证书配置

Admin API 示例

创建新的上游服务

curl -X POST http://localhost:8081/admin/resources/upstreams/my-upstream \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-upstream",
    "type": "RoundRobin",
    "nodes": ["127.0.0.1:8001", "127.0.0.1:8002"],
    "timeout": {
      "connect": 5,
      "read": 10,
      "send": 10
    }
  }'

创建服务

curl -X POST http://localhost:8081/admin/resources/services/my-service \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-service",
    "upstream_id": "my-upstream",
    "hosts": ["api.example.com"]
  }'

批量操作

curl -X POST http://localhost:8081/admin/batch \
  -H "Content-Type: application/json" \
  -d '{
    "dry_run": false,
    "operations": [
      {
        "operation_type": "create",
        "resource_type": "upstreams",
        "resource_id": "batch-upstream",
        "data": {
          "id": "batch-upstream",
          "type": "Random",
          "nodes": ["192.168.1.10:8080"]
        }
      },
      {
        "operation_type": "create",
        "resource_type": "services",
        "resource_id": "batch-service",
        "data": {
          "id": "batch-service",
          "upstream_id": "batch-upstream"
        }
      }
    ]
  }'

获取资源统计信息

curl http://localhost:8081/admin/resources

Admin Dashboard UI

• 路由：GET /admin 提供内置仪表板（static/admin_dashboard.html）。
  1. mcp_services、2) ssls、3) global_rules、4) routes、5) upstreams、6) services。
• 每张卡片显示 count 和根据 API 响应生成的格式化 last_updated。

从文件重新加载配置

# Uses default config.yaml
curl -X POST http://localhost:8081/admin/reload/config \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key"

# Or specify a different config path
curl -X POST http://localhost:8081/admin/reload/config \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{"config_path": "./config.yaml"}'

测试 Admin API

使用提供的测试脚本验证 Admin API 功能：

# Make the test script executable
chmod +x test-admin-api.sh

# Run comprehensive API tests
./test-admin-api.sh

有关 Admin API 的详细文档，请参阅 RUNTIME_CONFIG_API.md。

贡献指南

1. Fork 此仓库。
2. 创建分支并提交更改。
3. 创建 pull request 并等待合并。
4. 确保代码遵循 Rust 编码标准。