xpander-mcp-remote

A Node.js CLI SSE proxy with custom headers. Developed by [email protected] at xpander.ai.
Everyone is welcome to use, modify, and distribute this tool (see LICENSE for details).

Overview

xpander-mcp-remote provides a simple command-line interface (CLI) for bridging local STDIO to a remote SSE (Server-Sent Events) server. It allows you to send custom headers when connecting to the remote server and cleanly handles signals (e.g., Ctrl + C) for graceful shutdown.

Internally, it uses:

• @modelcontextprotocol/sdk for transport abstractions (SSE, STDIO).
• Node.js (ESM) syntax.

Installation

npm install --global xpander-mcp-remote

Note: Installing globally (--global) will make the CLI command xpander-mcp-remote available system-wide.
Alternatively, you can install it locally in a project and run it via npx xpander-mcp-remote.

Usage

After installing, you can run:

xpander-mcp-remote <https://your-server-url> [-H "Key: Value"]

Example:

xpander-mcp-remote https://api.example.com -H "Authorization: Bearer your_token"

You can specify multiple headers by repeating -H or --header:

xpander-mcp-remote https://api.example.com \
  -H "Authorization: Bearer your_token" \
  -H "X-Custom-Header: customValue"

Command-Line Arguments

1. Server URL (required)

   • Must be https:// or http://localhost (for local testing).
   • Example: https://api.example.com or http://localhost:3000

2. Headers (optional)

   • Use -H or --header to specify custom headers.
   • Each header must be in "Key: Value" format (with quotes).

What It Does

1. Opens a local server that listens on STDIO (standard input/output).
2. Connects to the remote SSE server at the specified URL, sending along any custom headers.
3. Forwards any messages received locally to the remote server, and vice versa.
4. Gracefully shuts down on errors or when you press Ctrl + C.

Logging / Debug

All important status messages and errors are printed to stderr (console.error in Node.js).
If you’re automating or monitoring, be sure to capture stderr to see logs like:

• Local STDIO server running
• Connected to remote server
• Error from local client:
• Error from remote server:

Programmatic Usage

Although intended as a CLI, you could also incorporate the core functionality in your own Node.js application by importing from the package source if you clone the repository or install locally.

Example (shared.js excerpt):

import { connectToRemoteServer, mcpProxy } from 'xpander-mcp-remote/src/shared.js';

// Connect and create a proxy programmatically
const remoteTransport = await connectToRemoteServer('https://api.example.com', { Authorization: 'Bearer your_token' });
mcpProxy({
  transportToClient: someLocalTransport,
  transportToServer: remoteTransport,
});

Contributing

1. Clone or fork this repository.
2. Install dependencies with npm install.
3. Make changes and test them locally.
4. Submit a pull request or patch to the project maintainers.

We welcome bug reports, feature requests, and pull requests!

License

See LICENSE for the full text. In summary, you are free to use, modify, and distribute this software under the terms of the MIT license.

Developed by:
xpander.ai
Contact: [email protected]