WebSocket MCP Bridge MCP server

MCP Server Runner is a WebSocket server implementation that bridges WebSocket clients with Model Context Protocol (MCP) servers. It manages connections between clients and MCP servers, handles bidirectional communication, and supports various configuration options to adapt to different deployment scenarios.

Installation

Prerequisites

• Rust 1.70 or higher
• An MCP server implementation executable

Installation Steps

To install and run the MCP Server Runner, follow these steps:

1. Clone the repository or download the source code
2. Build the project:

cargo build --release

3. The executable will be available in the target/release directory

Configuration

The MCP Server Runner can be configured through environment variables or a JSON configuration file.

Environment Variables

PROGRAM=        # Path to the MCP server executable (required if no config file)
ARGS=           # Comma-separated list of arguments for the MCP server
HOST=0.0.0.0    # Host address to bind to (default: 0.0.0.0)
PORT=8080       # Port to listen on (default: 8080)
CONFIG_FILE=    # Path to JSON configuration file

Any additional environment variables will be passed to the MCP server process.

JSON Configuration

For more complex setups, you can use a JSON configuration file:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/workspace"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  },
  "default_server": "filesystem",
  "host": "0.0.0.0",
  "port": 8080
}

Configuration Priority

The server uses the following priority order when determining configuration:

1. Command-line specified config file
2. CONFIG_FILE environment variable
3. Individual environment variables (PROGRAM, ARGS, etc.)
4. Default values

Usage

Starting the Server

Using Environment Variables

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

Using a Configuration File

# Specify the config file as an argument
cargo run --release config.json

# Or use the CONFIG_FILE environment variable
CONFIG_FILE=config.json cargo run --release

Connecting to the Server

To connect to the MCP Server Runner from a client application:

const ws = new WebSocket("ws://localhost:8080");

// Set up event handlers
ws.onopen = () => {
  console.log("Connected to MCP server");
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log("Received message:", message);
};

ws.onerror = (error) => {
  console.error("WebSocket error:", error);
};

ws.onclose = () => {
  console.log("Disconnected from MCP server");
};

// Send a message to the server
ws.send(JSON.stringify({
  type: "your-message-type",
  // Add message payload here
}));

Docker Deployment

Using Docker Compose

The MCP Server Runner can be easily deployed using Docker:

docker-compose up --build

Custom Docker Configuration

You can create your own Docker configuration by using the provided Dockerfile:

FROM rust:latest as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bullseye-slim
COPY --from=builder /app/target/release/mcp-server-runner /usr/local/bin/
EXPOSE 8080
ENTRYPOINT ["mcp-server-runner"]

Troubleshooting

Enable Debug Logging

For more detailed logs to troubleshoot issues:

RUST_LOG=debug cargo run --release

Common Issues

• Connection refused: Ensure the port isn't blocked by a firewall
• Server not starting: Check if the specified MCP server executable exists and is executable
• Connection closed unexpectedly: Look at server logs for possible errors in the MCP server process

Limitations

• Supports only one client connection at a time
• Does not support WebSocket SSL/TLS (use a reverse proxy for secure connections)
• No built-in authentication mechanism

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.