MCP Protocol Bridging Component

This utility, named MCP Gateway Adapter, functions as a high-efficiency protocol transformation proxy. Its primary purpose is to establish a functional communication channel between conventional HTTP endpoints and clients adhering to the MCP (Model Context Protocol) specification. It achieves this by enabling direct interaction for MCP consumers with established HTTP backends, completely bypassing the need for any alteration to the existing server logic.

Core Overview

This solution is engineered utilizing Pingora, an exceptionally performant gateway proxy library. Pingora is architected to manage massive volumes of request proxy traffic, having served as the infrastructure underpinning core Cloudflare services, consistently processing beyond 40 million requests per second globally for many years. It represents the technological foundation for a substantial fraction of worldwide internet traffic.

HTTP Translation to MCP

This operational mode facilitates communication between clients such as Cursor Desktop and remote HTTP systems using SSE (Server-Sent Events), even when the target servers natively lack SSE support.

• Illustrative Deployment Topology:
• Endpoint A is situated locally, accessible at 127.0.0.1:8090
• Endpoint B resides externally at api.example.com
• By employing the MCP Gateway Adapter, both service endpoints are effectively converted into MCP-compatible services without any requisite codebase adjustments.
• Clients interface with Endpoint A and Endpoint B exclusively via the MCP framework. The Adapter intelligently determines MCP requests and routes them to the correct backend infrastructure.

mermaid graph LR A["Cursor Desktop Client"] <--> |SSE Stream| B["MCP Gateway Adapter"] A2["Alternative Client"] <--> |Streamable Http| B["MCP Gateway Adapter"] B <--> |HTTP 127.0.0.1:8090| C1["Existing Web Service"] B <--> |HTTPS api.example.com| C2["External Web Service"]

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

Supported Communication Formats (Specification)

Presently supports the following transport mechanisms: SSE and Streamable HTTP protocols: - ✅ Streamable HTTP (Stateless) Activated: 2025-03-26 - Universal access: ip:port/mcp - Dedicated service access: ip:port/api/{service_identifier}/mcp

• ✅ Server-Sent Events (SSE) Activated: 2024-11-05
• Universal access: ip:port/sse
• Dedicated service access: ip:port/api/{service_identifier}/sse

Utilize the path IP:PORT/sse for the SSE transport mode. Utilize the path IP:PORT/mcp for the Streamable HTTP transport mode.

Compatible MCP Consumer Applications

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

Key Capabilities

• Protocol Interoperability: Effortlessly translates data flows between HTTP standards and MCP requirements.
• Non-Invasive Deployment: Achieves full compatibility with pre-existing HTTP service infrastructures.
• Client Enablement: Grants MCP-native clients direct invocation capability over standard HTTP resources.
• Low-Footprint Proxy: Minimalist structural design ensures highly efficient protocol mediation.
• Multi-Tenant Isolation: Supports distinct configuration settings and endpoint segregation per registered tenant.
• Dynamic State Modification: Allows configuration parameters to be adjusted while the service is operational.
• Management Interface: Provides a RESTful administrative API for live configuration control.

Initial Setup Guide

Deployment Steps

bash

Obtain source code

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

Start service using configuration file

cargo run -- -c config.yaml

Debugging with Inspector (start service first)

npx @modelcontextprotocol/inspector node build/index.js

Connect to http://127.0.0.1:6274/

Choose "SSE" and input 0.0.0.0:8080/sse, then initiate connection

Alternatively, select "Streamable HTTP" and input 0.0.0.0:8080/mcp

Multi-Tenant Access Scheme

The MCP Access Gateway facilitates multi-tenancy, where each distinct client configuration exposes services via segregated paths: - /api/{mcp-service-id}/sse (For SSE traffic) - /api/{mcp-service-id}/mcp (For Streamable HTTP traffic)

Configuration Example: yaml

config.yaml snippet for service definition

mcps: - id: primary-api # Accessible via /api/primary-api/sse or /api/primary-api/mcp ... - id: secondary-data # Accessible via /api/secondary-data/sse or /api/secondary-data/mcp ...

To reach all registered services concurrently, utilize the root paths: - 0.0.0.0:8080/mcp (Streamable HTTP aggregate) - 0.0.0.0:8080/sse (SSE aggregate)

Configuration Parameterization

1. -c config.yaml
2. The -c (or --config) flag dictates the location of the YAML configuration document.
3. This document itemizes all upstream APIs intended for proxying and protocol conversion by the Adapter.

config.yaml Detailed Structure

The configuration file enables granular control over multiple distinct MCP services, defining upstream targets and routing logic independently. Key configuration sections include:

1. mcps - Inventory of defined MCP services
2. id: A unique identifier serving as the prefix for access URLs.
3. upstream_id: Reference key linking to an entry in the upstreams section.
4. path: Pointer to the OpenAPI documentation schema. Accepts local filesystem paths (e.g., schema/spec.json) or remote URLs (e.g., https://api.docs.org/v3/swagger.json). Supports both JSON and YAML schema formats.
5. routes: Specific, customized routing rules (Optional).

6. upstream: Service-specific parameters for the backend connection (Optional).

7. upstreams - Definitions for backend destinations

8. id: The unique identifier referenced by the mcps section.
9. nodes: A list of target backend addresses along with their associated load-balancing weights.
10. type: Load balancing methodology (e.g., roundrobin, random, ip_hash).
11. scheme: The protocol used to connect to the backend (http/https).
12. pass_host: Policy for relaying the HTTP Host header.
13. upstream_host: Value to substitute into the Host header for backend requests.

Comprehensive Configuration Blueprint: yaml

Configuration document example

mcps: - id: data-source-one upstream_id: backend_A path: ./schemas/api_v1.json

• id: external-catalog upstream_id: backend_B path: https://catalog.vendor.com/openapi.yaml

• id: telemetry-ingest upstream_id: backend_C routes: # Custom path definitions

  • id: get_metric_data operation_id: fetch_sensor_reading uri: /readings/{sensor_id} method: GET meta: {}

upstreams: - id: backend_A headers: X-Auth-Token: "secret-key-alpha" nodes: "service.internal:9000": 5

• id: backend_B nodes: "remote.host.net:443": 1 type: random scheme: https pass_host: preserve

To launch the MCP Protocol Bridging Component using the configuration file: bash cargo run -- -c config.yaml

Containerized Deployment (Docker)

Rapid Local Launch

bash

Substitute /path/to/your/config.yaml with the actual host path

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

Building Custom Docker Image (Optional)

• Ensure Docker is installed.
• Obtain repository and build the image locally: bash

Clone repository

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

Build image (using custom tag)

docker build -t myregistry/mcp-adapter:latest .

• Execute Container: bash

Use environment variables for configuration path mapping

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

Environmental Settings

• port: Defines the network interface port where the Adapter listens (Default: 8080).

Common Application Scenarios

• Incremental System Modernization: Facilitates a phased transition of services from pure HTTP to MCP utilization.
• Mixed Infrastructure Support: Enables legacy HTTP assets to participate seamlessly within the MCP operational environment.
• Protocol Coexistence: Allows the creation of systems that natively manage both communication standards concurrently.

Use Case Example: When modern, AI-centric clients leveraging MCP require data from older HTTP-based microservices, the MCP Gateway Adapter sits intermediately, executing flawless protocol transformation.

Acknowledgement to @limcheekin for a practical implementation case study: https://limcheekin.medium.com/building-your-first-no-code-mcp-server-the-fabric-integration-story-90da58cdbe1f

Live Configuration Management via Admin Interface

The Adapter now integrates a RESTful Administration API, enabling modification of operational parameters without service interruption.

Admin API Capabilities

• Instant Configuration Updates: Modify service definitions, upstream pools, routing maps, and other settings dynamically.
• Dependency Checking: Automated validation ensures structural integrity before applying configuration changes.
• Atomic Batches: Execute sequences of updates as a single, guaranteed operation.
• Pre-flight Validation: Test proposed changes using a 'dry-run' mode.
• State Monitoring: Access metrics related to the current configuration layout.

Admin API Setup

Incorporate this block into config.yaml to activate the Admin Endpoint:

yaml access_point: admin: address: "127.0.0.1:8081" # Interface for administrative commands api_key: "secure-key-456" # Optional security token

Admin API Path Definitions

Resource Manipulation

• GET /admin/resources - Overview of all managed resources and basic metrics.
• GET /admin/resources/{type} - List all entries of a specific resource category.
• GET /admin/resources/{type}/{id} - Retrieve the details of one specific resource.
• POST /admin/resources/{type}/{id} - Provision a new resource instance.
• PUT /admin/resources/{type}/{id} - Overwrite/update an existing resource.
• DELETE /admin/resources/{type}/{id} - Terminate a resource.

Advanced Control Flows

• POST /admin/validate/{type}/{id} - Validate the syntax and logic of a specific resource configuration.
• POST /admin/batch - Execute a series of operations together.
• POST /admin/reload/{type} - Force a refresh of all instances within a specific resource type.
• POST /admin/reload/config - Re-read the entire configuration file (defaults to config.yaml). Accepts an optional JSON body: { "config_path": "new/path/config.yaml" }

Managed Resource Categories

• upstreams - Definitions for backend server groups.
• services - High-level service mappings.
• routes - Specific request handling rules.
• global_rules - System-wide operational policies.
• mcp_services - Definitions specific to MCP exposure.
• ssls - SSL/TLS certificate definitions.

Admin API Request Examples

Updating an Upstream Group

bash curl -X POST http://localhost:8081/admin/resources/upstreams/new-backend-pool \ -H "Content-Type: application/json" \ -H "x-api-key: secure-key-456" \ -d '{ "id": "new-backend-pool", "type": "RoundRobin", "nodes": ["10.0.0.5:9000"], "timeout": {"connect": 3, "read": 8} }'

Executing a Batch Operation

bash curl -X POST http://localhost:8081/admin/batch \ -H "Content-Type: application/json" \ -H "x-api-key: secure-key-456" \ -d '{ "dry_run": false, "operations": [ { "operation_type": "update", "resource_type": "upstreams", "resource_id": "backend_A", "data": {"timeout": {"send": 20}} } ] }'

Accessing the Web Management Interface

• Access URL: GET /admin serves an integrated administrative dashboard (static/admin_dashboard.html).
• The UI visualizes status for: 1) mcp_services, 2) ssls, 3) global_rules, 4) routes, 5) upstreams, 6) services.
• Each dashboard element displays the current count and the timestamp of the last_updated configuration retrieved via the API.

Triggering File Configuration Reload

bash

Reload using the primary configuration file

curl -X POST http://localhost:8081/admin/reload/config \ -H "Content-Type: application/json" \ -H "x-api-key: secure-key-456"

Force load a different file path

curl -X POST http://localhost:8081/admin/reload/config \ -H "Content-Type: application/json" \ -H "x-api-key: secure-key-456" \ -d '{"config_path": "./production_settings.yaml"}'

For comprehensive reference on the Admin API functionality, consult RUNTIME_CONFIG_API.md.

Developer Contributions

1. Create a fork of this repository.
2. Establish a new feature branch.
3. Implement and commit your intended modifications.
4. Submit a Pull Request for review and potential integration.
5. Ensure all new code adheres to established Rust idiomatic practices.

REFERENCES: The concept of collecting and synthesizing external appraisals into a singular metric (aggregation) is widespread. For instance, in entertainment, review aggregators synthesize various critical opinions on media like films or software, impacting market perception and sometimes even financial outcomes. This tool performs an analogous function by gathering disparate HTTP requests and presenting them uniformly through the MCP lens.