ws-mcp: Bridge MCP Servers to WebSocket for Network Integration

Stop wrestling with stdio pipes when you need to integrate MCP servers into web applications or distributed systems. ws-mcp wraps any MCP stdio server with a clean WebSocket interface, letting you access powerful MCP capabilities over the network.

The stdio Integration Problem

MCP servers run as stdio processes by design, which works great for desktop applications but creates friction when you're building:

• Web applications that need server-side MCP integration
• Distributed systems where MCP servers run on different machines
• Browser-based tools that need direct MCP access
• Multi-tenant environments where you need centralized MCP orchestration

Network-First MCP Integration

ws-mcp solves this by providing a WebSocket wrapper around any MCP stdio server. Instead of managing subprocess pipes and stdio streams, you get a standard WebSocket endpoint that speaks MCP protocol.

# Turn any MCP server into a WebSocket service
uvx --refresh ws-mcp@latest --command "uvx mcp-server-fetch" --port 3002

# Now connect via WebSocket instead of stdio
ws://localhost:3002/mcp

Multiple Servers, Single Endpoint

Run multiple MCP servers through one WebSocket connection - perfect for complex workflows that need different capabilities:

# Combine file operations, HTTP requests, and search in one endpoint
uvx --refresh ws-mcp \
  --command "uvx --from wcgw@latest --python 3.12 wcgw_mcp" \
  --command "uvx mcp-server-fetch" \
  --command "npx -y @modelcontextprotocol/server-brave-search" \
  --port 3004

Your client connects to one WebSocket and gets access to file system operations, HTTP requests, and web search through the same interface.

Configuration-Driven Server Management

Define your MCP server stack in JSON and deploy consistently across environments:

{
  "servers": {
    "filesystem": {
      "command": "uvx",
      "args": ["--from", "wcgw@latest", "--python", "3.12", "wcgw_mcp"]
    },
    "web-fetch": {
      "command": "uvx", 
      "args": ["mcp-server-fetch"]
    },
    "search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {"BRAVE_API_KEY": "your-key-here"}
    }
  }
}

uvx --refresh ws-mcp --config production-config.json --port 3005

Real-World Integration Scenarios

Web Application Backend: Your React app needs to perform file operations and make external API requests. Instead of building custom endpoints, connect directly to ws-mcp and use existing MCP servers.

Development Tools: Build browser-based developer tools that need system access. Connect your web interface to ws-mcp running locally for seamless file operations and system commands.

Multi-User Environments: Deploy ws-mcp in containers or serverless functions. Each user gets their own MCP server instance accessible via WebSocket, with proper environment isolation.

API Gateway Integration: Use ws-mcp as a microservice that translates between HTTP/REST and MCP protocols. Your existing API infrastructure can now consume MCP capabilities.

Zero-Config Startup

Get started immediately with sensible defaults:

# Starts with wcgw (file ops) and fetch (HTTP) servers
uvx --refresh ws-mcp@latest
# → WebSocket available at ws://localhost:10125

Environment Management

Pass secrets and configuration cleanly to your MCP servers:

# Individual environment variables
export BRAVE_API_KEY=your-key
uvx --refresh ws-mcp --env BRAVE_API_KEY=$BRAVE_API_KEY --command "npx -y @modelcontextprotocol/server-brave-search"

# Or use .env files for complex configurations
uvx --refresh ws-mcp --env-file .env --config servers.json

Integration Pattern

Instead of this complexity:

# Managing stdio subprocesses directly
import subprocess
import json

proc = subprocess.Popen(['uvx', 'mcp-server-fetch'], 
                       stdin=subprocess.PIPE, 
                       stdout=subprocess.PIPE)
# ... handle stdio protocol, process management, error handling

You get this simplicity:

// Clean WebSocket integration
const ws = new WebSocket('ws://localhost:3002');
ws.send(JSON.stringify({
  type: 'tool_call',
  tool: 'fetch',
  args: { url: 'https://api.example.com/data' }
}));

ws-mcp handles the stdio complexity, process lifecycle, and protocol translation so you can focus on building features instead of managing infrastructure.