MCPNyx

MCPNyx 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

Installation & Usage

Option 1: Run with npx (No Installation)

Run MCPNyx directly without installing:

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

Option 2: Global Installation

Install MCPNyx globally to use the mcpnyx or nyxmcp commands:

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

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

# Or use the nyxmcp alias
nyxmcp --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: 3055)
• --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: sse with --stdio or --config, 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

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 exposes the following endpoints:

• SSE endpoint: http://localhost:<port>/sse
• POST messages: http://localhost:<port>/message
• Streamable HTTP endpoint: http://localhost:<port>/mcp
• WebSocket endpoint: ws://localhost:<port>/message

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

Example Usage

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:

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

Advanced Usage

stdio → SSE

Convert a stdio MCP server to SSE:

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

SSE → stdio

Convert an SSE MCP server to stdio:

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

Config → Streamable HTTP (Stateful)

Run multiple servers with stateful Streamable HTTP:

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

Why MCP?

Model Context Protocol standardizes how AI tools exchange data. If your MCP server only speaks stdio, MCPNyx 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 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 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.git
cd mcpnyx

# 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 3055 is already in use, specify a different port:

npx -y @alsania-io/mcpnyx --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 --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 is part of the Alsania I/O ecosystem, built with the Alsania soverign 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.