remote-mcp-rust

A lightweight Rust proxy that bridges local stdio MCP clients to remote HTTP MCP servers. Use it to connect Claude Desktop, Cursor, Claude Code, or any Model Context Protocol client to a remote MCP server — with a single binary, zero runtime dependencies, and built-in OAuth 2.0 support.

Why Rust? The original Remote MCP is JavaScript. This rewrite eliminates the JS supply-chain attack surface, starts instantly, and ships as a single ~3.5 MB binary with zero runtime dependencies.

Quick Start

# Install from source
cargo install --git https://github.com/qJkee/remote-mcp-rust

# Or download a prebuilt binary from GitHub Releases

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "my-remote-server": {
      "command": "remote-mcp-rust",
      "args": ["--url", "https://mcp.example.com/v1"]
    }
  }
}

That's it. Claude will discover all tools, resources, and prompts from the remote server automatically.

Usage

Basic

remote-mcp-rust --url https://mcp.example.com/v1

With authentication

# Bearer token via header flag
remote-mcp-rust --url https://mcp.example.com/v1 \
  -H "Authorization: Bearer <token>"

# Or via environment variable
HTTP_HEADER_Authorization="Bearer <token>" \
  remote-mcp-rust --url https://mcp.example.com/v1

With tool filtering

# Only expose specific tools
remote-mcp-rust --url https://mcp.example.com/v1 \
  --allow-tools search,get_page

# Hide specific tools
remote-mcp-rust --url https://mcp.example.com/v1 \
  --deny-tools dangerous_tool,admin_reset

With OAuth 2.0

remote-mcp-rust --url https://mcp.example.com/v1 \
  --oauth \
  --client-id <client-id> \
  --auth-url https://auth.example.com/authorize \
  --token-url https://auth.example.com/token \
  --scopes read,write

This opens your browser for authorization, receives the callback on a temporary local server, and injects the token automatically. Tokens are cached in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) so you only authenticate once. Use --clear-token to force re-authentication.

Claude Desktop Configuration

Minimal

{
  "mcpServers": {
    "remote": {
      "command": "remote-mcp-rust",
      "args": ["--url", "https://mcp.example.com/v1"]
    }
  }
}

With auth header

{
  "mcpServers": {
    "remote": {
      "command": "remote-mcp-rust",
      "args": [
        "--url", "https://mcp.example.com/v1",
        "-H", "Authorization: Bearer <token>"
      ]
    }
  }
}

With environment variables

{
  "mcpServers": {
    "remote": {
      "command": "remote-mcp-rust",
      "args": ["--url", "https://mcp.example.com/v1"],
      "env": {
        "HTTP_HEADER_Authorization": "Bearer <token>"
      }
    }
  }
}

With tool filtering

{
  "mcpServers": {
    "remote": {
      "command": "remote-mcp-rust",
      "args": [
        "--url", "https://mcp.example.com/v1",
        "-H", "Authorization: Bearer <token>",
        "--allow-tools", "search,get_page,create_issue"
      ]
    }
  }
}

CLI Reference

remote-mcp-rust [OPTIONS] --url <URL>

Options:
      --url <URL>                  Remote MCP server URL [env: REMOTE_MCP_URL]
  -H, --header <HEADERS>           HTTP headers ("Name: Value"), repeatable
      --allow-tools <TOOLS>        Tool allowlist, comma-separated
      --deny-tools <TOOLS>         Tool denylist, comma-separated
      --no-reconnect               Disable auto-reconnect on upstream disconnect
      --reconnect-delay-ms <MS>    Reconnect delay [default: 1000]
      --log-level <LEVEL>          Log level [env: RUST_LOG] [default: info]
  -h, --help                       Print help
  -V, --version                    Print version

OAuth options:
      --oauth                      Enable OAuth 2.0 authentication
      --client-id <ID>             OAuth client ID
      --client-secret <SECRET>     OAuth client secret (optional)
      --auth-url <URL>             Authorization endpoint
      --token-url <URL>            Token endpoint
      --scopes <SCOPES>            Scopes, comma-separated
      --redirect-port <PORT>       Local callback port [default: 8914]
      --clear-token                Clear cached token and re-authenticate

Environment Variables

Variable	Description
REMOTE_MCP_URL	Remote server URL (alternative to --url)
HTTP_HEADER_<Name>	Set HTTP header (underscores become hyphens)
RUST_LOG	Log level filter (alternative to --log-level)

Example: HTTP_HEADER_X_Api_Key=abc123 sets the header X-Api-Key: abc123.

Building from Source

# Build (includes OAuth + keychain support by default)
cargo build --release

# Without OAuth (minimal binary)
cargo build --release --no-default-features

# Binary location
./target/release/remote-mcp-rust

Requires Rust 1.75+.

How It Works

Claude Desktop/Cursor/CLI
    | stdio (JSON-RPC)
+----------------------+
|  remote-mcp-rust     |
|                      |
|  stdio server        |
|       |              |
|  middleware chain     |
|  (logging, filter)   |
|       |              |
|  HTTP/SSE client     |
+------+---------------+
       | HTTP
Remote MCP Server

The proxy forwards all MCP operations (tools, resources, prompts, subscriptions, completions) bidirectionally. Notifications from the remote server are relayed to the local client in real time.

Comparison with the JS Version

	remote-mcp-rust	Remote-MCP (JS)
Binary size	~3.5 MB single binary	Node.js + node_modules
Runtime dependencies	Zero	npm dependency tree
Startup time	Instant	Node.js cold start
Supply-chain surface	Compiled, no runtime deps	npm supply-chain risk
OAuth 2.0	Built-in with OS keychain	Built-in
Tool filtering	Built-in allow/deny lists	Middleware-based
Config compatibility	HTTP_HEADER_* env vars	HTTP_HEADER_* env vars
Install	Single binary or cargo install	npm install

Alternatives

• Remote-MCP (JS) — the original JavaScript implementation. Pick it if you're already in a Node.js environment or want to write custom middleware in JS. Pick remote-mcp-rust if you want a zero-dependency binary, faster startup, or a smaller attack surface.
• Built-in remote support — some MCP clients are adding native HTTP/SSE transport. Check your client's docs first. This proxy is useful when your client only supports stdio, or when you need features like tool filtering or OAuth that the client doesn't provide natively.

License

MIT