@alsania-io/mcpnyx-u

v1.1.0

Published

2 months ago

MCPNyx Unified - Advanced MCP server for remote access. Run multiple MCP stdio/SSE servers through unified streamableHttp/SSE/WS endpoint with mcp-remote integration.

0High
0Medium
0Low

sigmasauer07

echo-dev

sigmasauer-dev

mcp nyx streamableHttp sse websocket server modelcontextprotocol http stream alsania proxy remote bridge

MCPNyx Unified

MCPNyx Unified is an advanced MCP (Model Context Protocol) proxy server designed for the Nyx extension. It allows you to run multiple MCP stdio-based and SSE-based servers and expose them through a single unified SSE/HTTP/WebSocket endpoint. This enables Nyx and other MCP-compatible tools to connect to multiple remote MCP servers and tools via a single proxy.

Features

🔄 Multiple Transport Protocols: stdio, SSE, WebSocket, Streamable HTTP
🌐 Unified Proxy: Aggregate multiple MCP servers behind a single endpoint
🔌 Flexible Routing: Route requests to different MCP servers based on configuration
📡 Real-time Communication: SSE and WebSocket support for live updates
��️ Stateful & Stateless Modes: Choose between session-based or stateless operation
🎯 Nyx Integration: Optimized for use with the Nyx browser extension
⚡ Dynamic Configuration Switching: Hot-reload configurations without restart (with --dynamic flag)

🚀 Quick Start

For a quick 5-minute setup guide, see QUICKSTART.md

Installation & Usage

Option 1: Run with npx (No Installation)

Run MCPNyx Unified directly without installing:

npx -y @alsania-io/mcpnyx-u@latest --config path/to/config.json

# Default transport is streamableHttp on /mcp endpoint
# Accessible at: http://localhost:3057/mcp

Option 2: Global Installation

Install MCPNyx Unified globally to use the mcpnyx-u commands:

# Install globally
npm install -g @alsania-io/mcpnyx-u

# Run with mcpnyx-u command
mcpnyx-u --config path/to/config.json

# Or use the nyxmcp-u alias
nyxmcp-u --config path/to/config.json

CLI Options

--config, -c <path>: (required) Path to a JSON configuration file (see below)
--port <number>: Port to run the proxy server on (default: 3057)
--baseUrl <url>: Base URL for SSE clients (default: http://localhost:<port>)
--ssePath <path>: Path for SSE subscriptions (default: /sse)
--messagePath <path>: Path for SSE messages (default: /message)
--logLevel <info|none>: Set logging level (default: info)
--outputTransport stdio | sse | ws | streamableHttp: Output MCP transport (default: streamableHttp with --config, sse with --stdio, stdio with --sse or --streamableHttp)
--streamableHttpPath "/mcp": Path for Streamable HTTP (default: /mcp)
--stateful: Run StreamableHttp in stateful mode
--sessionTimeout 60000: Session timeout in milliseconds (stateful StreamableHttp modes only)
--header "x-user-id: 123": Add one or more custom headers
--dynamic: Enable dynamic configuration switching without restart (config→SSE/WS/StreamableHttp only) [boolean] [default: false]

Advanced: Dynamic Configuration Switching

When started with the --dynamic flag, MCPNyx Unified supports hot-reloading of configurations without restarting the server:

# Start with dynamic configuration switching enabled
mcpnyx-u --config ./config.json --port 3057 --dynamic

# Switch to a different configuration via API
curl -X POST http://localhost:3057/api/config/switch \
  -H "Content-Type: application/json" \
  -d '{"config_name": "production-config"}'

# Reload current configuration (e.g., after file changes)
curl -X POST http://localhost:3057/api/config/reload

Supported with all output transports:

SSE with dynamic switching: --outputTransport sse --dynamic
WebSocket with dynamic switching: --outputTransport ws --dynamic
Streamable HTTP with dynamic switching: --outputTransport streamableHttp --dynamic

Dynamic Configuration API Endpoints:

List configurations: GET http://localhost:3057/api/configs
Get current config: GET http://localhost:3057/api/config/current
Switch configuration: POST http://localhost:3057/api/config/switch
Reload config: POST http://localhost:3057/api/config/reload
Health check: GET http://localhost:3057/api/health

Configuration

Create a JSON configuration file to define your MCP servers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-database", "postgresql://..."]
    },
    "remote-sse": {
      "url": "https://remote-mcp-server.example.com/sse",
      "transport": "sse"
    }
  }
}

Endpoints

Once running, MCPNyx Unified exposes the following endpoints:

MCP Protocol Endpoints

SSE endpoint: http://localhost:3057/sse
POST messages: http://localhost:3057/message
Streamable HTTP endpoint: http://localhost:3057/mcp
WebSocket endpoint: ws://localhost:3057/message

Web Configuration GUI (when using `--dynamic` flag)

When running with the --dynamic flag, MCPNyx Unified provides a modern web interface for easy configuration management:

Web GUI: http://localhost:3057/ - Visual interface for configuration management
Real-time Status: View system health and current configuration
One-click Switching: Switch configurations with a single click
Configuration Preview: See available configurations and server counts
Auto-refresh: Real-time updates every 30 seconds

Dynamic Configuration API (when using `--dynamic` flag)

List configurations: GET http://localhost:3057/api/configs
Get current config: GET http://localhost:3057/api/config/current
Switch configuration: POST http://localhost:3057/api/config/switch
Reload config: POST http://localhost:3057/api/config/reload
Health check: GET http://localhost:3057/api/health

(You can customize the paths with --ssePath, --messagePath, and --streamableHttpPath.)

Example Usage

Dynamic Configuration Example

Run with dynamic configuration switching enabled to allow hot-reloading of MCP servers:

# Start with dynamic switching
mcpnyx-u --config ./config.json --port 3057 --dynamic --outputTransport streamableHttp

# In another terminal, switch configurations without restarting
curl -X POST http://localhost:3057/api/config/switch \
  -H "Content-Type: application/json" \
  -d '{"config_name": "alternative-config"}'

# Check current configuration
curl http://localhost:3057/api/config/current

Basic Configuration

Create a config file (e.g., nyx-config.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
    },
    "alsaniamcp": {
      "command": "npx",
      "args": ["-y", "@alsania-io/mcp@latest", "server", "start", "-c", "/home/user/.mcp/config.json"]
    }
  }
}

Run MCPNyx Unified:

npx -y @alsania-io/mcpnyx-u@latest --config nyx-config.json --port 3057

Advanced Usage

stdio → SSE

Convert a stdio MCP server to SSE:

npx -y @alsania-io/mcpnyx-u --stdio "npx -y @modelcontextprotocol/server-filesystem /" \
                          --port 3057 --baseUrl http://localhost:3057

SSE → stdio

Convert an SSE MCP server to stdio:

npx -y @alsania-io/mcpnyx-u --sse "https://remote-mcp-server.example.com/sse"

Config → Streamable HTTP (Stateful)

Run multiple servers with stateful Streamable HTTP:

npx -y @alsania-io/mcpnyx-u --config ./config.json \
                          --outputTransport streamableHttp \
                          --port 3057 \
                          --stateful \
                          --sessionTimeout 300000

Why MCP?

Model Context Protocol standardizes how AI tools exchange data. If your MCP server only speaks stdio, MCPNyx Unified exposes an SSE/HTTP/WebSocket interface so remote clients (like the Nyx extension, MCP Inspector, or Claude Desktop) can connect without extra server changes. It also allows you to aggregate multiple MCP servers behind a single endpoint.

Advanced Features

MCPNyx Unified is designed with modularity and flexibility in mind:

✅ Supports both stdio and SSE MCP servers in one config
✅ Automatically derives the JSON-RPC version from incoming requests
✅ Package information (name and version) is retransmitted where possible
✅ Stdio-to-SSE mode uses standard logs; SSE-to-stdio mode logs via stderr
✅ SSE-to-SSE mode provides automatic reconnection with exponential backoff
✅ Health endpoints can be added for monitoring
✅ CORS support for cross-origin requests
✅ Custom headers for authentication and routing

Integration with Nyx

MCPNyx Unified is optimized for use with the Nyx browser extension, providing:

🎯 Seamless MCP Integration: Connect Nyx to multiple MCP servers
🔄 Real-time Updates: SSE support for live tool and resource updates
🛡️ Secure Communication: Support for authentication headers
📊 Session Management: Stateful mode for persistent connections

Development

Building from Source

# Clone the repository
git clone https://github.com/alsania-io/mcpnyx-unified.git
cd mcpnyx-unified

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start -- --config ./config.json

Development Mode

npm run dev -- --config ./config.json

Troubleshooting

Port Already in Use

If port 3057 is already in use, specify a different port:

npx -y @alsania-io/mcpnyx-u --config config.json --port 3007

Connection Issues

Ensure your MCP servers are properly configured in the config file
Check that stdio commands are executable and have correct paths
Verify SSE URLs are accessible and return proper SSE responses
Check firewall settings if connecting to remote servers

Logging

Enable detailed logging:

npx -y @alsania-io/mcpnyx-u --config config.json --logLevel info

MCPB Bridge (Claude Desktop Integration)

MCPNyx Unified supports a two-process architecture for Claude Desktop via the bundled mcpb-stdio-bridge:

Architecture:

Claude Desktop  ──(stdio)──►  mcpb-stdio-bridge  ──(HTTP)──►  MCPNyx-U :3059  ──►  downstream servers

Step 1: Start the MCPNyx-U HTTP server (background service):

node dist/index.js \
  --config ~/mcpconfig.json \
  --port 3059 --host 127.0.0.1 \
  --outputTransport streamableHttp \
  --streamableHttpPath /mcp \
  --logLevel none

Step 2: Configure Claude Desktop (~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "MCPNyx Unified": {
      "command": "node",
      "args": ["/path/to/dist/mcpb-stdio-bridge.js"],
      "env": {
        "MCPNYX_URL": "http://127.0.0.1:3059/mcp"
      }
    }
  }
}

Or install as an MCPB bundle — see MCPB_BUNDLE_GUIDE.md.

Notes:

The bridge handles both application/json and text/event-stream responses.
Tool names containing . are automatically sanitized to _ for Claude Desktop compatibility and reverse-mapped on call.
Set DEBUG=true in env for bridge debug output (goes to stderr).

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Acknowledgments

MCPNyx Unified is part of the Alsania I/O ecosystem, built with the Alsania sovereign vision and purpose in mind. It is designed for the Nyx extension.

Aligned with the Alsania AI Protocol v1.0 Imagined by Sigma. Powered by Echo.