MCP Access Point

1# MCP Access Point  
2
3`MCP Access Point` is a lightweight protocol conversion gateway tool designed to establish a communication bridge between traditional `HTTP` services and `MCP` (Model Context Protocol) clients. It enables MCP clients to interact directly with existing HTTP services without requiring any server-side interface modifications.  
4<p align="center">
5  <a href="./README.md"><img alt="README in English" src="https://img.shields.io/badge/English-4578DA"></a>
6  <a href="./README_CN.md"><img alt="简体中文版" src="https://img.shields.io/badge/简体中文-F40002"></a>
7  <a href="https://deepwiki.com/sxhxliang/mcp-access-point"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
8  <a href="https://zread.ai/sxhxliang/mcp-access-point"><img alt="中文文档" src="https://img.shields.io/badge/中文文档-4578DA"></a>
9</p>
10
11![Admin Dashboard](assets/admin_dashboard.png)
12
13## Introduction  
14This project is built on `Pingora` - an ultra-high performance gateway proxy library capable of supporting massive-scale request proxy services. Pingora has been used to build services that handle core traffic for the Cloudflare platform, consistently serving over 40 million requests per second across the internet for years. It has become the technical cornerstone supporting a significant proportion of traffic on the Cloudflare platform.
15
16## HTTP to MCP  
17This mode allows clients like `Cursor Desktop` to communicate with remote HTTP servers through `SSE`, even when the servers themselves don't support the SSE protocol.
18
19- Example setup includes two services:  
20  - Service 1 runs locally at `127.0.0.1:8090`  
21  - Service 2 runs remotely at `api.example.com`  
22- Through the `MCP Access Point`, both services can be converted to MCP services without any code modifications.  
23- Clients communicate with `Service 1` and `Service 2` via the MCP protocol. The MCP Access Point automatically distinguishes MCP requests and forwards them to the appropriate backend services.
24
25```mermaid
26graph LR
27   A["Cursor Desktop"] <--> |SSE| B["MCP Access Point"]
28   A2["Other Desktop"] <--> |Streamable Http| B["MCP Access Point"]
29   B <--> |http 127.0.0.1:8090| C1["Existing API Server"]
30   B <--> |https//api.example.com| C2["Existing API Server"]
31  
32   style A2 fill:#ffe6f9,stroke:#333,color:black,stroke-width:2px
33   style A fill:#ffe6f9,stroke:#333,color:black,stroke-width:2px
34   style B fill:#e6e6af,stroke:#333,color:black,stroke-width:2px
35   style C1 fill:#e6ffe6,stroke:#333,color:black,stroke-width:2px
36   style C2 fill:#e6ffd6,stroke:#333,color:black,stroke-width:2px
37```
38
39### Transport Type (Specification)
40Currently supports `SSE` and `Streamable HTTP` protocols:
41- ✅ Streamable HTTP (stateless) 2025-03-26
42  - All services: `ip:port/mcp`
43  - Single service: `ip:port/api/{service_id}/mcp`
44  
45- ✅ SSE 2024-11-05
46  - All services: `ip:port/sse`
47  - Single service: `ip:port/api/{service_id}/sse`
48
49use `IP:PORT/sse` for `SSE` 
50use `IP:PORT/mcp` for `Streamable HTTP` 
51
52### Supported MCP clients
53- ✅ [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
54- ✅ [Cursor Desktop](https://docs.cursor.com/context/model-context-protocol)
55- ✅ [Windsurf](https://docs.windsurf.com/plugins/cascade/mcp#model-context-protocol-mcp)
56- ✅ [VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
57- ✅ [Trae](https://docs.trae.ai/ide/model-context-protocol)
58
59## Core Features
60- **Protocol Conversion**: Seamless conversion between HTTP and MCP protocols
61- **Zero-Intrusive Integration**: Full compatibility with existing HTTP services
62- **Client Empowerment**: Enables MCP clients to directly call standard HTTP services
63- **Lightweight Proxy**: Minimalist architecture with efficient protocol conversion
64- **Multi-tenancy**: Independent configuration and endpoints for each tenant
65- **Runtime Configuration Management**: Dynamic configuration updates without service restart
66- **Admin API**: RESTful API for real-time configuration management
67
68## Quick Start  
69
70### Installation  
71```bash
72# Install from source
73git clone https://github.com/sxhxliang/mcp-access-point.git
74cd mcp-access-point
75cargo run -- -c config.yaml
76
77# Use inspector for debugging (start service first)
78npx @modelcontextprotocol/inspector node build/index.js
79# Access http://127.0.0.1:6274/
80# Select "SSE" and enter 0.0.0.0:8080/sse, then click connect
81# or select "Streamable HTTP" and enter 0.0.0.0:8080/mcp
82```
83
84### Multi-tenancy Support
85The MCP Access Gateway supports multi-tenancy, where each tenant can configure multiple MCP services accessible via:
86- `/api/{mcp-service-id}/sse` (for SSE)
87- `/api/{mcp-service-id}/mcp` (for Streamable HTTP)
88
89Example configuration:
90```yaml
91# config.yaml example (supports multiple services)
92
93mcps:
94  - id: service-1 # Access via /api/service-1/sse or /api/service-1/mcp
95    ... # Service configuration
96  - id: service-2 # Access via /api/service-2/sse or /api/service-2/mcp
97    ... # Service configuration
98  - id: service-3 # Access via /api/service-3/sse or /api/service-3/mcp
99    ... # Service configuration
100```
101
102To access all services simultaneously, use:
103- `0.0.0.0:8080/mcp` (Streamable HTTP)
104- `0.0.0.0:8080/sse` (SSE)
105
106### Configuration Details
1071. **`-c config.yaml`**
108   - `-c` (or `--config`) specifies the configuration file path (`config.yaml`).
109   - This file defines the APIs that the MCP Access Point will proxy and convert.
110
111### config.yaml Example
112The configuration file supports multi-tenancy, allowing independent configuration of upstream services and routing rules for each MCP service. Key configuration items include:
113
1141. **mcps** - MCP service list
115   - `id`: Unique service identifier used to generate access paths
116   - `upstream_id`: Associated upstream service ID
117   - `path`: OpenAPI specification file path. Supports local files (e.g., `config/openapi.json`) and remote HTTP/HTTPS URLs (e.g., `https://petstore.swagger.io/v2/swagger.json`). Both JSON and YAML formats are supported.
118   - `routes`: Custom routing configuration (optional)
119   - `upstream`: Upstream service specific configuration (optional)
120
1212. **upstreams** - Upstream service configuration
122   - `id`: Upstream service ID
123   - `nodes`: Backend node addresses and weights
124   - `type`: Load balancing algorithm (roundrobin/random/ip_hash)
125   - `scheme`: Upstream protocol (http/https)
126   - `pass_host`: HTTP Host header handling
127   - `upstream_host`: Override Host header value
128
129Complete configuration example:
130```yaml
131# config.yaml example (supports multiple services)
132mcps:
133  - id: service-1 # Unique identifier, accessible via /api/service-1/sse or /api/service-1/mcp
134    upstream_id: 1
135    path: config/openapi_for_demo_patch1.json # Local OpenAPI spec path
136
137  - id: service-2 # Unique identifier
138    upstream_id: 2
139    path: https://petstore.swagger.io/v2/swagger.json # Remote OpenAPI spec
140
141  - id: service-3 
142    upstream_id: 3
143    routes: # Custom routing
144      - id: 1
145        operation_id: get_weather
146        uri: /points/{latitude},{longitude}
147        method: GET
148        meta:
149          name: Get Weather
150          description: Retrieve weather information by coordinates
151          inputSchema: # Optional input validation
152            type: object
153            required:
154              - latitude
155              - longitude
156            properties:
157              latitude:
158                type: number
159                minimum: -90
160                maximum: 90
161              longitude:
162                type: number
163                minimum: -180
164                maximum: 180
165
166upstreams: # Required upstream configuration
167  - id: 1
168    headers: # Headers to send to upstream service
169      X-API-Key: "12345-abcdef"        # API key
170      Authorization: "Bearer token123" # Bearer token
171      User-Agent: "MyApp/1.0"          # User agent
172      Accept: "application/json"       # Accept header
173    nodes: # Backend nodes (IP or domain)
174      "127.0.0.1:8090": 1 # Format: address:weight
175
176  - id: 2 
177    nodes:
178      "127.0.0.1:8091": 1
179
180  - id: 3 
181    nodes:
182      "api.weather.gov": 1
183    type: roundrobin # Load balancing algorithm
184    scheme: https # Protocol
185    pass_host: rewrite # Host header handling
186    upstream_host: api.weather.gov # Override Host
187```
188
189To run the MCP Access Gateway with config file:
190```bash
191cargo run -- -c config.yaml
192```
193
194## Running via Docker  
195
196### Run Locally for quick start
197
198```bash
199# Note: Replace /path/to/your/config.yaml with actual path
200docker run -d --name mcp-access-point --rm \
201  -p 8080:8080 \
202  -e port=8080 \
203  -v /path/to/your/config.yaml:/app/config/config.yaml \
204  ghcr.io/sxhxliang/mcp-access-point:main
205```
206
207
208### Build Docker Image (Optional)  
209- install docker
210- clone repository and build image
211```bash
212# Clone repository
213git clone https://github.com/sxhxliang/mcp-access-point.git
214cd mcp-access-point
215
216# Build image
217docker build -t liangshihua/mcp-access-point:latest .
218```
219
220- Run Docker Container
221```bash
222# Using environment variables (service running on host)
223# Note: Replace /path/to/your/config.yaml with actual path
224
225docker run -d --name mcp-access-point --rm \
226  -p 8080:8080 \
227  -e port=8080 \
228  -v /path/to/your/config.yaml:/app/config/config.yaml \
229  liangshihua/mcp-access-point:latest
230```
231
232### Environment Variables  
233- `port`: MCP Access Point listening port (default: 8080)
234
235## Typical Use Cases  
236
237- **Progressive Architecture Migration**: Facilitate gradual transition from HTTP to MCP  
238- **Hybrid Architecture Support**: Reuse existing HTTP infrastructure within MCP ecosystem  
239- **Protocol Compatibility**: Build hybrid systems supporting both protocols  
240
241**Example Scenario**:  
242When MCP-based AI clients need to interface with legacy HTTP microservices, the MCP Access Gateway acts as a middleware layer enabling seamless protocol conversion.
243
244Many thanks to [@limcheekin](https://github.com/limcheekin) for writing an article with a practical example: https://limcheekin.medium.com/building-your-first-no-code-mcp-server-the-fabric-integration-story-90da58cdbe1f
245
246## Runtime Configuration Management
247
248The MCP Access Point now supports dynamic configuration management through a RESTful Admin API, allowing you to update configurations without restarting the service.
249
250### Admin API Features
251
252- **Real-time Configuration Updates**: Modify upstreams, services, routes, and other resources on-the-fly
253- **Dependency Validation**: Automatic validation of resource dependencies before changes
254- **Batch Operations**: Execute multiple configuration changes atomically
255- **Configuration Validation**: Dry-run mode to validate changes before applying
256- **Resource Statistics**: Monitor and track configuration state
257
258### Admin API Configuration
259
260Add the following to your `config.yaml` to enable the Admin API:
261
262```yaml
263access_point:
264  admin:
265    address: "127.0.0.1:8081"  # Admin API listening address
266    api_key: "your-api-key"    # Optional API key for authentication
267```
268
269### Admin API Endpoints
270
271#### Resource Management
272- `GET /admin/resources` - Get resource summary and statistics
273- `GET /admin/resources/{type}` - List all resources of a specific type
274- `GET /admin/resources/{type}/{id}` - Get a specific resource
275- `POST /admin/resources/{type}/{id}` - Create a new resource
276- `PUT /admin/resources/{type}/{id}` - Update an existing resource
277- `DELETE /admin/resources/{type}/{id}` - Delete a resource
278
279#### Advanced Operations
280- `POST /admin/validate/{type}/{id}` - Validate resource configuration
281- `POST /admin/batch` - Execute batch operations
282- `POST /admin/reload/{type}` - Reload a specific resource type
283- `POST /admin/reload/config` - Reload full configuration from file (defaults to `config.yaml`). Optional JSON body: `{ "config_path": "path/to/config.yaml" }`
284
285#### Supported Resource Types
286- `upstreams` - Backend server configurations
287- `services` - Service definitions
288- `routes` - Routing rules
289- `global_rules` - Global plugin rules
290- `mcp_services` - MCP service configurations
291- `ssls` - SSL certificate configurations
292
293### Admin API Examples
294
295#### Create a new upstream
296```bash
297curl -X POST http://localhost:8081/admin/resources/upstreams/my-upstream \
298  -H "Content-Type: application/json" \
299  -d '{
300    "id": "my-upstream",
301    "type": "RoundRobin",
302    "nodes": ["127.0.0.1:8001", "127.0.0.1:8002"],
303    "timeout": {
304      "connect": 5,
305      "read": 10,
306      "send": 10
307    }
308  }'
309```
310
311#### Create a service
312```bash
313curl -X POST http://localhost:8081/admin/resources/services/my-service \
314  -H "Content-Type: application/json" \
315  -d '{
316    "id": "my-service",
317    "upstream_id": "my-upstream",
318    "hosts": ["api.example.com"]
319  }'
320```
321
322#### Batch operations
323```bash
324curl -X POST http://localhost:8081/admin/batch \
325  -H "Content-Type: application/json" \
326  -d '{
327    "dry_run": false,
328    "operations": [
329      {
330        "operation_type": "create",
331        "resource_type": "upstreams",
332        "resource_id": "batch-upstream",
333        "data": {
334          "id": "batch-upstream",
335          "type": "Random",
336          "nodes": ["192.168.1.10:8080"]
337        }
338      },
339      {
340        "operation_type": "create",
341        "resource_type": "services",
342        "resource_id": "batch-service",
343        "data": {
344          "id": "batch-service",
345          "upstream_id": "batch-upstream"
346        }
347      }
348    ]
349  }'
350```
351
352#### Get resource statistics
353```bash
354curl http://localhost:8081/admin/resources
355```
356
357### Admin Dashboard UI
358
359- Route: `GET /admin` serves a built-in dashboard (`static/admin_dashboard.html`).
360  1) `mcp_services`, 2) `ssls`, 3) `global_rules`, 4) `routes`, 5) `upstreams`, 6) `services`.
361- Each card shows `count` and a formatted `last_updated` derived from the API response.
362
363#### Reload configuration from file
364```bash
365# Uses default config.yaml
366curl -X POST http://localhost:8081/admin/reload/config \
367  -H "Content-Type: application/json" \
368  -H "x-api-key: your-api-key"
369
370# Or specify a different config path
371curl -X POST http://localhost:8081/admin/reload/config \
372  -H "Content-Type: application/json" \
373  -H "x-api-key: your-api-key" \
374  -d '{"config_path": "./config.yaml"}'
375```
376
377### Testing the Admin API
378
379Use the provided test script to verify Admin API functionality:
380
381```bash
382# Make the test script executable
383chmod +x test-admin-api.sh
384
385# Run comprehensive API tests
386./test-admin-api.sh
387```
388
389For detailed Admin API documentation, see [RUNTIME_CONFIG_API.md](./RUNTIME_CONFIG_API.md).
390
391## Contribution Guidelines
3921. Fork this repository.
3932. Create a branch and commit your changes.
3943. Create a pull request and wait for it to be merged.
3954. Make sure your code follows the Rust coding standards.
396