LOCAL APP SETUP

Connect apps running on your computer

Install the connector on the computer running your MCP servers.
Moose Relay handles the secure tunnel—no router changes needed.

Already have a server in your workspace? Connect ChatGPT, Claude, or Muse to Moose Relay →

MACOS APP

Install Moose Relay for Mac

For Apple Silicon Macs running macOS 13 or later, use the Moose Relay menu bar app. The app includes the connector; Node.js and the CLI are not required.

Download Moose Relay for macOS ↗

  1. Open the downloaded DMG and drag Moose Relay to Applications.
  2. Open Moose Relay from Applications and select Sign in to set up this Mac. Complete sign-in in your browser to pair the Mac and start the connector automatically.
  3. In Local services, choose an app from the catalog or select Add manually to connect a local MCP server.

If you already paired this Mac with the CLI, the app offers to convert that pairing and keep your services. Keep the Mac awake and online while using its services.

The CLI instructions below are for Linux, Windows, Intel Macs, or anyone who prefers a terminal. Command-based MCP servers may still require their own runtime, such as Node.js.

CLI setup

STEP 1

Prepare your computer

Install Node.js 24 LTS, which includes npm. Node.js 22.19 or newer is required. Open a new terminal after installation.

macOS

Open Terminal. Intel and Apple Silicon are supported.

Linux

Open a terminal as your regular user. Background mode requires systemd with a working user session.

Windows

Open Windows Terminal as your regular user, type cmd, and press Enter to launch Command Prompt. Run the commands below there. This preserves the -- separator used to add stdio servers, which PowerShell can consume when running the npm script wrapper. Windows ARM64 uses the x64 Cloudflare connector through emulation.

node --version
npm --version

On Windows, keep using Command Prompt for installation, enrollment, and adding servers. You do not need a separate Cloudflare account or API key.

STEP 2

Install the Moose Relay CLI

Run these commands from any folder in your terminal:

npm install --global moose-relay-cli
moose-relay --help

The public npm package is moose-relay-cli; the command is moose-relay. The connector downloads and verifies Cloudflare’s tunnel executable when you enroll.

STEP 3

Connect this device to your account

  1. Sign in to your Moose Relay workspace.
  2. Under Local devices, select Connect device.
  3. Give the computer a recognizable name. Keep port 47831 unless another local application uses it.
  4. Select Create enrollment code, then run the command below on that computer.
  5. Paste the code from your own account at the prompt. It expires after ten minutes and can only be used once. Never enroll using a code sent by someone else.
moose-relay enroll

Enrollment starts a background connector. If service setup fails, your enrollment is saved: fix the reported service-manager issue and run moose-relay service install. Do not enroll again.

Free accounts allow 1 device; Paid accounts allow 3. Offline devices and pending enrollments still use an allowance slot.

STEP 4

Add a local MCP server

A server already listening on localhost

Start your local Streamable HTTP MCP server, then register its URL. Replace the example port and path with your server’s actual endpoint.

moose-relay add local-tools --name "Local tools" --url http://localhost:3000/mcp

A server launched as a command

For a stdio MCP server, provide its executable and arguments after --. Use an absolute path when launching a script directly, for example node "C:\path\to\server.js" on Windows. Commands such as npx are also supported.

moose-relay add my-tools --name "My tools" -- node /absolute/path/to/server.js

Windows (Command Prompt): register a server launched with npx directly. The connector handles the Windows launcher automatically:

moose-relay add test -- npx -y @modelcontextprotocol/server-everything stdio

The connector starts this stdio server automatically. No separate server terminal or HTTP URL is needed.

Only connect MCP servers you trust. Commands run with your user account’s permissions; the connector does not sandbox them. Tools that execute commands or modify files make those capabilities available through your authorized MCP clients.

The name after add is its namespace. Use lowercase letters, digits, or hyphens, beginning with a letter. Adding a server restarts the background connector automatically.

My local server requires authentication

Create a private secrets.env in the connector’s config directory, normally ~/.mooserelay on macOS/Linux or %USERPROFILE%\.mooserelay on Windows. Put the complete Authorization header in a variable, then reference its name:

# secrets.env — keep this file private
LOCAL_AUTH=Bearer YOUR_LOCAL_TOKEN

# Terminal
moose-relay add private-tools --url http://localhost:3000/mcp --authorization-env LOCAL_AUTH

For stdio servers, pass environment variable names using --env NAME1,NAME2 before --. Values remain on your device. After editing the environment file, run moose-relay service restart.

Local and remote servers share your plan’s server allowance: 5 on Free or 20 on Paid.

STEP 5

Check that everything is connected

moose-relay service status
moose-relay list

Refresh your workspace. Your device should appear online and its servers should appear under Connected servers. Select a server’s Test action to check it, then follow the AI tool setup guide to use it in a chat.

macOS

The LaunchAgent starts at login and restarts after failures. It cannot serve requests while the computer is asleep or you are logged out.

Linux

The systemd user service starts with your user manager. To run after logout or before login, an administrator can enable lingering for your account.

Windows

A scheduled task runs in the background at login, with failure retries. It runs only while your user is logged in; it is not a system-wide Windows Service.

DAY-TO-DAY

Manage the connector

moose-relay service restart
moose-relay cloudflared update
moose-relay remove local-tools
moose-relay service uninstall

Service uninstall stops autostart but keeps your enrollment. To disconnect the device from your account, revoke it in the dashboard. To upgrade, run npm install --global moose-relay-cli@latest, then moose-relay service install.

NEED A HAND?

Troubleshooting

Command not found or npm permission error

Open a new terminal and check your Node.js installation. Use a per-user Node.js setup if the global npm directory requires administrator access. On Windows, try moose-relay.cmd if PowerShell blocks the generated script.

Windows shows “Use add…” despite a -- separator

In Windows Terminal, type cmd and press Enter, then retry the command in Command Prompt. PowerShell can consume -- through the npm script wrapper. If you stay in PowerShell, explicitly invoke moose-relay.cmd.

Enrollment expired, failed, or is already in use

An expired or lost code needs a new enrollment from the dashboard. Revoke the unused pending device to free its slot. If the CLI says it is already enrolled, use moose-relay service install rather than reenrolling. Never share the private configuration file.

The device is offline

Keep the device awake and connected to the internet. Run moose-relay service status, then moose-relay service restart. On Linux, check journalctl --user -u moose-relay.service. On macOS/Windows, check service-error.log in the config directory.

Linux says the user service manager is unavailable

Run systemctl --user status from your regular login session. Minimal containers and systems without systemd cannot use this installer. Run moose-relay start in the foreground instead, with no background connector already running.

The device is online, but a server fails

For HTTP servers, confirm the server is running at the localhost URL you entered. For stdio servers, run the exact executable and arguments manually. Check local credentials and environment variables. Device connectivity does not guarantee that each local server is available.

← Back to Connected devices