mcp-bridge/spec.md

MCP-to-HTTP Bridge Specification

Overview

The MCP-to-HTTP Bridge is a lightweight Go binary that runs locally and exposes configurable HTTP REST endpoints, mapping them to Model Context Protocol (MCP) method calls executed via standard input/output (stdio) on a local MCP adapter. The service supports multiple MCP service configurations through YAML files, enabling flexible invocation of different MCP tools or services within the same application, with access restricted to local clients.

Objectives

Provide a simple Go binary that bridges local HTTP REST requests to local MCP method calls via stdio. Support modular configuration for multiple REST endpoints and MCP services using YAML files. Ensure local-only access with no external exposure. Enable easy extension for additional endpoints and MCP configurations without code changes.

Functional Requirements

1. Binary Installation

Name: mcp-bridge Platform: Cross-platform (Windows, macOS, Linux). Installation: Installable via a remote script (curl -sSL [URL_TO_install.sh] | bash) which downloads the appropriate pre-compiled binary from the ./dist directory for the user's architecture and places it into their system's PATH. Manual download and installation are also supported. Execution: Runs as a standalone process with YAML configuration files for endpoint and MCP service mappings.

2. HTTP Server

Transport: HTTP/1.1 (no HTTPS, as access is local-only). Port: Configurable via command-line flag (default: 8080). Endpoints: Expose RESTful endpoints (e.g., POST /) mapped to specific MCP methods/tools. Support JSON request/response bodies compatible with JSON-RPC 2.0 for MCP.

Access: Local-only, binds to localhost. CORS: Disabled (local-only access). Headers: Supports Mcp-Session-Id for session management.

3. MCP Integration

Transport: Uses MCP’s stdio transport to communicate with a local MCP adapter. Session Management: Initializes an MCP session per service configuration using the initialize method, maintaining unique Mcp-Session-Id per service. Method Calls: Maps HTTP POST requests to MCP tools/call method invocations, passing JSON payloads as parameters. Error Handling: Translates MCP errors into HTTP status codes (e.g., 400 for invalid params, 500 for server errors).

4. Configuration

File Format: YAML configuration files (e.g., config.yaml, service1.yaml, service2.yaml) loaded at startup. Main Config Structure (config.yaml):port: 8080 services:

• name: "default" config: "service1.yaml"
• name: "alternate" config: "service2.yaml"

port: HTTP server port. services: List of MCP service configurations.

Service Config Structure (e.g., service1.yaml):serviceName: "default" endpoints:

• path: "/example" mcp_method: "tools/call" tool_name: "example_tool"

serviceName: Unique identifier for the MCP service. endpoints: Array of endpoint mappings. path: HTTP path (e.g., /example). mcp_method: MCP method to invoke (e.g., tools/call). tool_name: MCP tool name to call.

Modularity: Multiple service configurations (e.g., service1.yaml, service2.yaml) can be loaded, each defining unique endpoints and tools. HTTP requests specify the service via a query parameter (e.g., POST /example?service=default). Reload: Supports dynamic config reload via SIGHUP signal or endpoint (e.g., POST /reload).

5. Modularity

Endpoint Extensibility: Add new HTTP endpoints by updating service YAML files without modifying the binary. Service Extensibility: Support multiple MCP services by loading additional YAML configs, each with its own session and endpoint mappings. Request Handling: Modular handler chain to route requests based on service query parameter, validate payloads, and dispatch to the correct MCP service. MCP Client: Reusable MCP client module for stdio communication, supporting multiple concurrent sessions for different services.

6. Input/Output

HTTP Request: Method: POST Path: Configured endpoint (e.g., /example?service=default). Body: JSON payload (e.g., {"key": "value"}). Headers: Content-Type: application/json.

HTTP Response: Status: 200 (success), 400 (invalid request/service), 500 (server error). Body: JSON response from MCP (e.g., {"jsonrpc": "2.0", "result": {...}, "id": 1}).

MCP Interaction: Sends JSON-RPC 2.0 requests to the local MCP adapter via stdio, scoped to the specified service’s session. Forwards MCP responses toHTTP client.

Non-Functional Requirements

Performance: Handle up to 100 concurrent HTTP requests with minimal latency (<100ms for local MCP calls). Security: Local-only access (binds to localhost). No authentication required, as the service is not exposed externally. Dependencies: Use Go standard library and minimal packages (e.g., encoding/json, net/http, gopkg.in/yaml.v3). Logging: Log requests, responses, and errors to stdout with configurable verbosity via flag (e.g., -v). Error Handling: Graceful handling of MCP failures, invalid configs, missing services, or malformed requests.

Constraints

MCP communication is via stdio to a local MCP adapter only. One MCP session per service configuration. No persistent storage; configurations are file-based. Local-only access (no remote binding).

Assumptions

A local MCP adapter is running and accessible via stdio. Users have Go installed or can download a prebuilt binary. YAML configuration files are valid and present at startup.

Deliverables

Go source code for the mcp-bridge binary, located in the ./src directory. Test suite located in the ./test directory. Pre-compiled, multi-architecture binaries located in the ./dist directory and tracked in Git. build-test-deploy.sh: A script to compile the binary for multiple architectures, run tests, and place artifacts in the ./dist directory. install.sh: An installation script for users to easily download and install the binary. Sample config.yaml and service1.yaml with one endpoint mapping. README with installation, configuration, and usage instructions. Basic test suite for HTTP endpoint handling, service routing, and MCP communication.