WebSocket MCP Wrapper

Overview

The ws‑mcp server is a lightweight gateway that exposes any standard MCP (Model Context Protocol) stdio server over WebSocket, enabling seamless integration with web‑based AI assistants such as Kibitz. By converting the traditional stdin/stdout interface into a bi‑directional WebSocket stream, it removes the need for custom adapters or local sockets, allowing developers to run multiple MCP services from a single endpoint and access them from any browser or WebSocket‑capable client.

This solution addresses the common pain point of deploying MCP servers in distributed or cloud environments. Native stdio servers are designed for local execution and rely on direct terminal access, which limits their use in containerized or remote setups. ws‑mcp solves this by wrapping the stdio interface and exposing it on a configurable TCP port, making it trivial to expose services like file management, HTTP fetching, or search APIs to an AI assistant without modifying the underlying MCP code. The server automatically handles framing, error propagation, and multiplexing of multiple services, so developers can run several MCP backends concurrently with minimal overhead.

Key capabilities include:

• Dynamic server orchestration – The configuration file lists any number of MCP servers to launch, each with its own command line or Docker image. This allows quick experimentation with different backends (e.g., Brave search, fetch, or custom Python tools) without changing the client code.
• Environment variable injection – Environment files or explicit flags let developers supply API keys and other secrets directly to the spawned MCP processes, keeping credentials out of source code.
• Port flexibility – A single ws‑mcp instance can listen on any port, and the flag may be repeated to expose multiple services simultaneously. This makes it ideal for microservice architectures where each tool is isolated yet accessible through a common WebSocket interface.
• Cross‑platform compatibility – The server is implemented in Rust and runs on any platform that supports WebSockets, ensuring consistent behavior across Linux, macOS, Windows, and cloud providers.

Typical use cases span from local prototyping to production deployments:

• AI‑powered web applications – A front‑end can connect over WebSocket to ws‑mcp, invoking file operations or web requests without exposing raw server ports.
• Containerized assistants – In Kubernetes, ws‑mcp can run as a sidecar that forwards MCP traffic to the main AI container, simplifying networking and scaling.
• Rapid prototyping – Developers can spin up a new MCP tool (e.g., a custom search engine) by adding its command to the config file, then immediately test it from Kibitz or any other MCP client.

By abstracting the intricacies of stdio communication and providing a unified WebSocket interface, ws‑mcp empowers developers to focus on building powerful AI tools while ensuring they remain easily consumable by modern web‑based assistants.