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

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

1. 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"
      ]
    }
  }
}

2. 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

Contributing

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

License

MIT License - see LICENSE file for details

Links

• Homepage: alsania-io.com
• Repository: github.com/alsania-io/mcpnyx
• Issues: github.com/alsania-io/mcpnyx/issues
• MCP Specification: modelcontextprotocol.io

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.