mcp-bridge

The MCP-to-HTTP Bridge is a lightweight local service that translates HTTP requests into Model Context Protocol (MCP) calls, allowing standard web tools to communicate with local MCP adapters.

Features

• HTTP to JSON-RPC translation for MCP adapters
• Configurable HTTP endpoints mapped to MCP methods
• Dynamic configuration reloading via SIGHUP or HTTP endpoint
• Structured JSON logging with configurable verbosity
• Graceful shutdown and process management
• Support for multiple concurrent adapters

Quick Install

To install the mcp-bridge binary to your local system, run the following command:

curl -sSL https://git.nixc.us/colin/mcp-bridge/raw/branch/main/install.sh | bash

This will download the appropriate binary for your system from the dist directory and place it in your path.

For custom installation options:

# Install to a custom directory
curl -sSL https://git.nixc.us/colin/mcp-bridge/raw/branch/main/install.sh | bash -s -- --dir=$HOME/bin

Usage

To run the bridge:

mcp-bridge -port 8091 -v info -config config.yaml

Options:

• -port: HTTP server port (overrides the port in config.yaml)
• -v: Log verbosity level (debug, info, warn, error)
• -config: Path to the configuration file (default: config.yaml)
• -version: Show version information and exit

Configuration

The bridge is configured using YAML files. A main config.yaml file defines the port and a set of services, and each service has its own YAML file defining its endpoints and the command to run its MCP adapter.

Main Configuration File (config.yaml)

port: 8091
services:
  service1:
    config: service1.yaml
    command:
      - /path/to/adapter
      - --arg1
      - --arg2
  service2:
    config: service2.yaml
    command:
      - /path/to/another/adapter

Service Configuration File (service1.yaml)

serviceName: service1
endpoints:
  - path: /api/v1/method1
    mcp_method: method1
    tool_name: tool1
  - path: /api/v1/method2
    mcp_method: method2
    tool_name: tool2

Configuration Reload

The bridge supports dynamic configuration reloading without restarting the service. There are two ways to trigger a reload:

1. Send a SIGHUP signal to the process:

   kill -SIGHUP <pid>
   

2. Send a POST request to the /reload endpoint:

   curl -X POST http://localhost:8091/reload
   

When a reload is triggered:

1. The configuration is reloaded from the config file
2. Existing services are gracefully shut down
3. New services are started based on the updated configuration
4. HTTP handlers are re-registered

Note: The HTTP server port cannot be changed during a reload.

Making Requests

To call an MCP adapter method, send an HTTP request to the configured endpoint:

curl -X POST http://localhost:8091/path/to/endpoint -d '{"param1": "value1", "param2": "value2"}'

The request body will be passed as parameters to the MCP method, and the response from the adapter will be returned as the HTTP response.

Error Handling

JSON-RPC errors returned by the adapter are translated to HTTP status codes:

• JSON-RPC errors are returned with HTTP 400 (Bad Request)
• Other errors are returned with HTTP 500 (Internal Server Error)

Building from Source

To build the project from source:

git clone https://git.nixc.us/colin/mcp-bridge.git
cd mcp-bridge
./build-test-deploy.sh

This will:

1. Run all tests
2. Build binaries for multiple platforms (linux/amd64, linux/arm64, darwin/amd64, darwin/arm64)
3. Create checksum files
4. Stage the binaries for commit

Development

Project Structure

mcp-bridge/
├── bin/                  # Compiled binaries for testing
├── dist/                 # Distribution binaries
├── src/                  # Source code
│   ├── main.go           # Main application
│   ├── handler/          # HTTP handlers
│   └── logger/           # Structured logging
├── test/                 # Tests
│   ├── adapter/          # Mock adapter for testing
│   └── integration_test.go # Integration tests
├── config.yaml           # Example configuration
├── service1.yaml         # Example service configuration
├── build-test-deploy.sh  # Build script
└── install.sh            # Installation script

Running Tests

# Run unit tests
go test ./src/...

# Run integration tests
go test ./test

License

See the LICENSE file for details.