MCP Server Runner is a WebSocket bridge that lets clients connect to an MCP server implementation through a WebSocket interface. It launches the MCP server process, forwards messages between the WebSocket client and the MCP server, and handles lifecycle events such as startup, errors, and shutdown. The runner supports a single connected client at a time and passes through standard error output from the MCP server for visibility in logs. To use it, configure which MCP server executable to run (via environment variables or a config file) and start the runner. Clients connect over WebSocket (for example ws://<host>:<port>) and exchange MCP messages as defined by the Model Context Protocol, enabling web apps to interact with MCP servers without embedding the server directly in the frontend.

Prerequisites:

• Rust toolchain (Rust 1.70 or higher) with cargo installed
• An MCP server executable to launch from the runner (or a path to build one)

Installation steps:

1. Clone the repository: git clone <repository-url> cd mcp-server-runner

2. Build the runner (Rust/Cargo): cargo build --release

   The compiled binary will be in target/release/

3. Prepare a sample MCP server executable path. If you don’t have one yet, build or place your MCP server binary somewhere accessible and note its path.

4. Run with environment configuration (example): export PROGRAM=/path/to/mcp-server-executable export ARGS="--option1 value1 --option2 value2" export HOST=0.0.0.0 export PORT=8080 cargo run --release

5. Alternative: provide a JSON config file and point the runner at CONFIG_FILE, then run accordingly (as described in the README): CONFIG_FILE=config.json cargo run --release

Notes and tips:

• The runner currently supports a single WebSocket client connection at a time; plan for multi-client support if needed.
• If you’re exposing the WebSocket server publicly, consider placing a reverse proxy (e.g., Nginx) with TLS termination in front of port 8080.
• Any environment variables prefixed with PIN or SECRET should be handled carefully; avoid logging sensitive values.
• The MCP server executable’s stdout/stderr will be logged by the runner; use this for debugging MCP-side issues.
• If you rely on a configuration file, ensure CONFIG_FILE points to a valid JSON with the expected structure and that the specified MCP server binary can be found via PROGRAM/ARGS when using environment-based configuration.