mcp-remote-deno

A Deno wrapper for the mcp-use proxy server that connects to remote MCP (Model Context Protocol) servers.

Features

Runs natively in Deno, utilizing NPM compatibility
Provides a clean CLI interface
Supports custom HTTP headers
TypeScript type definitions included

Prerequisites

Deno 1.37.0 or higher

Installation

No installation is needed if you have Deno installed. You can run the proxy directly.

Usage

The primary way to use this tool is via the command line to start the proxy server.

Running with `deno task` (Recommended)

If you have cloned the repository, you can use the predefined Deno task:

# Basic usage: Connects to the server and listens on default port 3334
deno task proxy:start <server-url>

# Example:
deno task proxy:start https://your-remote-mcp-server.com

# Specify a custom local callback port:
deno task proxy:start <server-url> [callback-port]

# Example with custom port 8080:
deno task proxy:start <server-url> 8080

# Include custom HTTP headers for the connection to the remote server:
deno task proxy:start <server-url> [callback-port] --header "Header-Name: Header-Value" --header "Another: Value"

# Example with headers:
deno task proxy:start https://your-remote-mcp-server.com 3334 --header "Authorization: Bearer mytoken" --header "X-Custom-ID: 12345"

Arguments:

<server-url>: (Required) The URL of the remote MCP server you want to connect to.
[callback-port]: (Optional) The local port the proxy should listen on for connections from your MCP client. Defaults to 3334.
--header "Name: Value": (Optional, repeatable) Custom HTTP headers to send to the remote MCP server during the initial connection.

Running with `deno run`

You can also run the proxy script directly using deno run. This requires specifying the necessary permissions precisely.

# Define permissions based on deno.json task
DENO_PERMISSIONS="--allow-env --allow-read --allow-sys=homedir --allow-run=open --allow-write=\"$HOME/.mcp-auth/mcp-remote-deno-0.0.1\" --allow-net=0.0.0.0,127.0.0.1,localhost"

# Basic usage with specific permissions:
deno run $DENO_PERMISSIONS src/proxy.ts <server-url> [callback-port]

# Example:
deno run $DENO_PERMISSIONS src/proxy.ts https://your-mcp-server.com

# Example with custom port and headers:
deno run $DENO_PERMISSIONS src/proxy.ts https://your-mcp-server.com 8080 --header "Authorization: Bearer mytoken"

Note: Using deno task proxy:start is simpler as it automatically applies the correct permissions defined in deno.json.

API

You can also use the library programmatically in your Deno projects:

import { startProxy, runProxy } from "jsr:@mmizutani/mcp-remote-deno@^100.1";

// Using the wrapped function
await startProxy("https://your-mcp-server.com", 3334, {
  "Authorization": "Bearer token"
});

// Or using the direct import from mcp-use
await runProxy("https://your-mcp-server.com", 3334, {
  "Authorization": "Bearer token"
});

Development

# Run in development mode with auto-reload
deno task dev https://your-mcp-server.com

# Check types
deno check mod.ts cli.ts

# Format code
deno fmt

How It Works

This project uses Deno's NPM compatibility feature to directly import and use the mcp-use package without the need for Node.js or a subprocess. It wraps the functionality in a Deno-friendly API with TypeScript type definitions.

Bidirectional Proxying Explained

The core functionality relies on establishing two sets of communication channels based on the MCP HTTP+SSE transport specification:

Client <-> Proxy:
- The proxy starts an HTTP server locally (defaulting to port 3334, configurable via the [callback-port] argument).
- Your local MCP client connects to this server's SSE endpoint to receive messages from the proxy.
- The client sends messages to the proxy via HTTP POST requests to a specific endpoint provided by the proxy upon connection.
Proxy <-> Server:
- The proxy makes an initial HTTP connection to the remote MCP server specified by the <server-url> argument to establish an SSE connection. Any custom headers provided via the --header flag are sent during this setup.
- The proxy receives messages from the remote server via this SSE connection.
- The proxy sends messages to the remote server via HTTP POST requests to the endpoint provided by the server during the initial handshake.

Once both connections are established, the proxy relays messages between them:

HTTP POST messages received from the Client are forwarded as HTTP POST messages to the Server.
SSE messages received from the Server are forwarded as SSE messages to the Client.

This creates a transparent bridge, allowing your local client to communicate with the remote server using the standard MCP HTTP+SSE transport.

sequenceDiagram
    participant Client
    participant Proxy as Proxy (mcp-remote-deno)
    participant Server

    Client->>+Proxy: GET / (Establish SSE connection, http://localhost:3334)
    Proxy-->>-Client: SSE stream opened, provides POST endpoint (/client-post)

    Proxy->>+Server: GET / (Establish SSE connection, <server-url>, Headers)
    Server-->>-Proxy: SSE stream opened, provides POST endpoint (/server-post)

    loop Message Exchange
        Client->>Proxy: POST /client-post (MCP Request)
        Proxy->>Server: POST /server-post (Forwarded MCP Request)
        Server-->>Proxy: SSE event (MCP Response/Notification)
        Proxy-->>Client: SSE event (Forwarded MCP Response/Notification)

        Server-->>Proxy: SSE event (MCP Request/Notification)
        Proxy-->>Client: SSE event (Forwarded MCP Request/Notification)
        Client->>Proxy: POST /client-post (MCP Response)
        Proxy->>Server: POST /server-post (Forwarded MCP Response)
    end

    Client->>Proxy: Close Connection
    Proxy->>Server: Close Connection
    Server-->>Proxy: Connection Closed
    Proxy-->>Client: Connection Closed

If either the client or the server disconnects, the proxy ensures the other connection is also terminated gracefully.

License

MIT - See the LICENSE file for details.

6.1 KiB Raw Blame History