Model Context

Bridge to run an MCP server via WebSocket with process management and graceful shutdown.

rust

GitHub Stars

rust

Language

7 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "mcp-mirror-yonaka15_mcp-server-runner": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "ARGS": "-y,@modelcontextprotocol/server-github",
        "HOST": "0.0.0.0",
        "PORT": "8080",
        "PROGRAM": "npx",
        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_***"
      }
    }
  }
}

You run an MCP server through a WebSocket bridge that starts an MCP server process, manages its I/O, and exposes a stable WebSocket interface for clients. This lets web apps and other network clients interact with MCP servers without embedding the server logic directly, while providing graceful shutdown and centralized error handling.

How to use

To run an MCP server through the bridge, first prepare the environment and then start the runner. You connect your client to the WebSocket endpoint to send requests and receive responses from the MCP server.

Typical usage pattern

Start the MCP Server Runner with your MCP server command configured via environment variables.
Connect your WebSocket client to the runner’s address and begin exchanging messages with the MCP server through the bridge.

How to install

Prerequisites you need before installing and running the MCP Server Runner.

# Install Rust (stable toolchain is recommended) and required build tools
# You should have Rust 1.70 or higher installed

# Optional: install Docker for containerized usage
# Docker and docker-compose may be used for deployment

Configuration and usage notes

Configure the runtime by setting environment variables that describe which MCP server to launch and how to expose the WebSocket interface.

The following environment variables are used by the MCP Server Runner.

PROGRAM: Path to the MCP server executable (required)
ARGS: Comma-separated list of arguments for the MCP server
HOST: Host address to bind to (default: 0.0.0.0)
PORT: Port to listen on (default: 8080)
GITHUB_PERSONAL_ACCESS_TOKEN: Token used by the MCP server when invoking GitHub resources (example shown below)

Examples

Set up an MCP server that uses an npx-based MCP server package and run the runner, then connect a client.

export PROGRAM=npx
export ARGS=-y,@modelcontextprotocol/server-github
export PORT=8080
export GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_***

# Build and run the MCP Server Runner
cargo build
cargo run

Available tools

websocket_bridge

Manages WebSocket connections between clients and the MCP server.

process_manager

Launches and monitors the MCP server process, handling I/O and lifecycle.

shutdown_handler

Coordinates graceful shutdown and error handling across components.

Built by

VeilStrat

AI signals for GTM teams