RelayForge-MCP

RelayForge MCP

RelayForge MCP is a portable Model Context Protocol (MCP) server that gives compatible AI clients a controlled bridge to local files, processes, search, and document utilities.

It supports MCP Streamable HTTP, so it can be connected to web-based AI clients that accept a remote MCP URL, as well as local MCP clients.

What it provides

RelayForge exposes tools for:

• Reading, writing, moving, and inspecting files
• Editing text blocks
• Directory creation and listing
• File/content search with progressive results
• Starting and interacting with terminal processes
• Listing and terminating processes
• PDF creation and manipulation
• Excel, DOCX, image, and text handling
• Configuration and local tool history

The default HTTP endpoint is:

http://127.0.0.1:3334/mcp

Requirements

• Node.js 18 or newer
• npm
• Git
• Windows, macOS, or Linux

For a fixed public HTTPS URL, you also need a reverse proxy or tunnel provider. The included launcher supports a Cloudflare Named Tunnel when cloudflared is installed.

Quick start

Clone the repository:

git clone https://github.com/ediooutros500-spec/RelayForge-MCP.git
cd RelayForge-MCP
npm ci
npm run build

Windows

Double-click:

start-relayforge.bat

Or run:

.\start-relayforge.bat

On startup, the Windows launcher checks the repository for updates. If the local checkout is clean and a fast-forward update is available, it updates automatically before rebuilding and starting the MCP server. It also clears a stale RelayForge instance occupying the configured port and downloads a verified portable cloudflared binary when required.

Linux / macOS

chmod +x start-relayforge.sh
./start-relayforge.sh

Connect an AI client

In any AI client that supports remote MCP over Streamable HTTP, add an MCP server using:

Name: RelayForge MCP
Transport: Streamable HTTP
URL: http://127.0.0.1:3334/mcp

A browser-hosted AI service usually cannot reach your computer's 127.0.0.1. In that case, expose RelayForge through HTTPS and register the resulting public URL instead.

Examples of compatible client types include:

• Web AI products with custom MCP server support
• Desktop AI clients with MCP support
• IDE agents that accept MCP servers
• Custom applications using the MCP SDK

The exact UI varies by product, but the URL always points to the RelayForge /mcp endpoint.

Fixed public URL

Quick tunnels create a new URL each time. For a stable URL, use a named tunnel or your own reverse proxy.

RelayForge's Windows launcher supports a Cloudflare Named Tunnel.

1. Copy the example environment file:

Copy-Item .env.example .env

2. Configure a permanent hostname in your Cloudflare Tunnel dashboard, for example:

mcp.example.com -> http://127.0.0.1:3334

3. Put only the local secrets in .env:

RELAYFORGE_PUBLIC_URL=https://mcp.example.com/mcp
CLOUDFLARE_TUNNEL_TOKEN=your_named_tunnel_token

4. Start RelayForge:

start-relayforge.bat

The launcher will start the local MCP server, start the named tunnel, and print the fixed public MCP URL.

Never commit .env, tunnel tokens, API keys, passwords, or private certificates.

You can use another HTTPS reverse proxy instead of Cloudflare. Point it to:

http://127.0.0.1:3334/mcp

Authentication

RelayForge supports an optional Bearer token on the HTTP endpoint.

Set:

RELAYFORGE_HTTP_TOKEN=use-a-long-random-secret

Then configure your MCP client to send:

Authorization: Bearer use-a-long-random-secret

When RelayForge binds to a non-loopback address, a token is required.

For public deployments, use HTTPS plus authentication. A secret URL path alone should not be treated as strong authentication.

Environment variables

Variable	Default	Purpose
RELAYFORGE_HTTP_HOST	127.0.0.1	HTTP bind address
RELAYFORGE_HTTP_PORT	3334	HTTP port
RELAYFORGE_MCP_PATH	/mcp	MCP endpoint path
RELAYFORGE_HTTP_TOKEN	empty	Optional Bearer token
RELAYFORGE_CONFIG_DIR	~/.relayforge	Local runtime configuration
RELAYFORGE_OFFLINE_MODE	1 in launchers	Disables background network feature-flag fetches
RELAYFORGE_DISABLE_TELEMETRY	1 in launchers	Disables inherited telemetry
RELAYFORGE_PUBLIC_READONLY	0	Restrict exposed tools to read-only subset
RELAYFORGE_PUBLIC_URL	empty	Fixed public URL shown by launcher
CLOUDFLARE_TUNNEL_TOKEN	empty	Optional named-tunnel token, stored locally only

Legacy DC_* environment variables remain supported internally for compatibility with the upstream codebase, but new deployments should use RELAYFORGE_*.

Security model

RelayForge can execute commands and modify files when full tools are enabled. Treat access to the MCP endpoint like access to your computer.

Recommended practices:

1. Bind locally to 127.0.0.1 unless remote access is required.
2. Use HTTPS for any remote connection.
3. Set RELAYFORGE_HTTP_TOKEN for public endpoints.
4. Keep .env outside version control.
5. Restrict allowedDirectories in the RelayForge configuration when full filesystem access is unnecessary.
6. Keep the inherited blocked-command list enabled.
7. Use RELAYFORGE_PUBLIC_READONLY=1 for low-risk remote testing.
8. Rotate tunnel tokens immediately if they are ever exposed.

An empty allowedDirectories array means filesystem access is unrestricted by that setting.

Local-only mode

If you do not need a web AI to connect over the internet, no tunnel is required:

npm run start:http

The MCP endpoint will be:

http://127.0.0.1:3334/mcp

npm scripts

npm run build         Compile TypeScript
npm run start:http    Start MCP Streamable HTTP server
npm run start:local   Start the lightweight local gateway
npm test              Run the upstream-compatible test suite
npm run inspector     Open the MCP Inspector against the stdio server

Architecture

AI client
   |
   | MCP Streamable HTTP
   v
RelayForge HTTP transport
   |
   v
RelayForge MCP server
   |
   +-- filesystem tools
   +-- search tools
   +-- process / terminal tools
   +-- document tools
   +-- configuration / history

RelayForge currently contains no Supabase transport or Supabase runtime dependency. Remote access is provided through standard MCP Streamable HTTP plus whichever HTTPS reverse proxy or tunnel you choose. A separate authenticated relay layer can be added later without changing the MCP tool layer.

Building from source

npm ci
npm run build

Node 18+ is required. Node 20 or 22 LTS is recommended.

After the build, the Streamable HTTP entry point is:

dist/http-mcp/server.js

Verify with an MCP client

Use the MCP Inspector or another MCP client against:

http://127.0.0.1:3334/mcp

A successful connection should discover the available RelayForge tools and allow tools/list and tools/call.

Repository secrets policy

This repository intentionally excludes:

• .env
• .env.local
• .relayforge-data/
• .educational-data/
• tunnel logs
• downloaded tunnel binaries
• API keys and access tokens
• local device/session files

Use .env.example only as a template.