MCP Relay

Your AI in the cloud. Your MCP servers on your computer.

Connect your cloud AI agent to the local MCP servers you choose, through a single remote endpoint.

Windows & Linux · Outbound connection · Your choice of MCP servers

Get started · How it works · Why MCP Relay? · Guides

_{A real local run: Server, Client and a small stdio MCP server on one machine, called from a Python MCP client.}

Bring your local MCP tools to your cloud AI

Your AI agent runs in the cloud. The MCP servers it needs run on your computer. MCP Relay connects them: a Server in the cloud receives the agent's requests, and a local Client relays them to your configured MCP servers.

No inbound port or port forwarding is needed on your computer. The local Client opens the connection to the cloud Server and reconnects automatically if that connection is interrupted.

MCP Relay works with MCP servers you supply, using stdio or Streamable HTTP. It does not bundle or guarantee any particular server. The actions your AI can perform depend on the servers you configure and their own permissions.

Project status: the MVP is implemented. There is no stable release or compatibility guarantee yet. The current setup supports one Relay Server, one Relay Client, one user and one computer.

How it works

flowchart LR
    subgraph Cloud
        AI[Your AI agent] -->|MCP over HTTPS|Server[Relay Server]
    end
    subgraph Your computer
        Client[Relay Client] --> A[Local MCP server]
        Client --> B[Another MCP server]
    end
    Client -->|Outbound secure WebSocket|Server

• Your cloud AI agent connects to one MCP endpoint.
• Relay Server routes requests between the AI agent and your computer.
• Relay Client connects your local MCP servers under names you choose.

The tools of your local MCP servers appear directly in your AI's tool list, named <alias>_<tool> (for example localtools_read_file), and the list updates itself when servers start, stop or change. relay_status reports the state of the whole chain. You can restrict each server to the tools you want your AI to see.

You can also let your AI manage the configured servers by explicitly enabling administration on the local Client. This is optional and disabled unless you set admin: true.

Why MCP Relay?

MCP Relay still needs a public HTTPS/WSS address for its Server: a cloud host behind a TLS reverse proxy, or a secure tunnel in front of the Server. Tools such as mcp-remote solve the opposite problem, connecting a local MCP client to a remote server.

Get started

You need a cloud AI agent supporting MCP over Streamable HTTP with an Authorization header, a cloud host for Relay Server, and your Windows or Linux computer. For remote access, provide an HTTPS/WSS address through a TLS reverse proxy or secure tunnel. MCP Relay does not provision hosting, DNS or TLS.

1. Install on the cloud host and your computer

Linux - requires Bash, curl and tar:

curl -fsSL https://raw.githubusercontent.com/kxlion/mcp-relay/main/scripts/install.sh | bash

Windows - PowerShell 5.1 or newer:

iex (irm https://raw.githubusercontent.com/kxlion/mcp-relay/main/scripts/install.ps1)

The installers set up uv, managed Python 3.14.4 and the mcp-relay command for your user account. They start guided setup when an interactive terminal is available. Choose Server-only on your cloud host and Client connected to a remote Server on your computer, after preparing the credentials below. You can cancel setup and rerun mcp-relay onboard when ready.

These commands execute a remote script and install the moving main branch. Review the scripts before running them if needed. To skip guided setup, set MCP_RELAY_SETUP=skip in the installer's environment.

curl -fsSL https://raw.githubusercontent.com/kxlion/mcp-relay/main/scripts/install.sh -o install-mcp-relay.sh
less install-mcp-relay.sh
bash install-mcp-relay.sh

irm https://raw.githubusercontent.com/kxlion/mcp-relay/main/scripts/install.ps1 -OutFile .\install-mcp-relay.ps1
Get-Content .\install-mcp-relay.ps1
.\install-mcp-relay.ps1

2. Prepare your credentials

Create two different, randomly generated secrets and supply them through process environment variables or a private ~/.mcp-relay/.env file:

Each token must contain 32–256 printable ASCII characters without spaces. Use a secure secret generator; length alone does not make a token secure. On Windows, the default directory is %USERPROFILE%\.mcp-relay. Restrict the .env file to your user account (0600 on Linux).

MCP Relay does not generate or save tokens for you. The Client token must be available before Client onboarding. Keep tokens out of YAML, command arguments and URLs, and transfer them between machines through a secure channel.

3. Start the cloud Server

On the cloud host, run guided setup and select Server-only:

mcp-relay onboard

The Server has two separate listeners. With a TLS proxy on the same host, keep both bound to loopback and route requests as follows:

Keep these internal ports private. The proxy must support long-lived WebSocket connections and preserve authentication headers. Onboarding configures listener settings; you configure the proxy separately.

Start the Server:

mcp-relay config validate
mcp-relay server

RELAY_SERVER_MCP_HOST=127.0.0.1
RELAY_SERVER_MCP_PORT=8000
RELAY_SERVER_CLIENT_HOST=127.0.0.1
RELAY_SERVER_CLIENT_PORT=8001

4. Connect your local MCP servers

On your computer, run guided setup and choose Client connected to a remote Server:

mcp-relay onboard

Select Remote and enter your wss://relay.example.com/ws address. The Client reads the RELAY_CLIENT_TOKEN you supplied in step 2.

Declare your MCP servers under mcp_servers in the generated ~/.mcp-relay/config.yaml. For example, if you already run a local Streamable HTTP MCP server on port 9000, add:

mcp_servers:
  localtools:
    url: http://127.0.0.1:9000/mcp

Replace that URL with your server's address. For a server launched as a local process, use command with its executable and arguments instead of url. Registry-based declarations use source. Add tools: to publish only some of a server's tools. See the server configuration reference for the entry formats and per-server credentials.

You choose and configure the underlying MCP servers separately; Relay does not supply browser, desktop or terminal tools of its own.

Start the Client:

mcp-relay config validate
mcp-relay client

Keep the cloud Server and local Client running. Manual YAML edits take effect after restarting the Client. Use Ctrl+C in the corresponding terminal to stop either process.

5. Connect your cloud AI agent

Add an MCP connection to your agent:

Supply the token through your AI host's secret settings. For clients using the following configuration format and supporting environment interpolation:

mcp_servers:
  mcp_relay:
    url: https://relay.example.com/mcp
    headers:
      Authorization: "Bearer ${RELAY_MCP_TOKEN}"
    supports_parallel_tool_calls: false

Ask your AI agent to:

Call relay_status and tell me which MCP servers and tools are available on my computer.

A live Client report confirms the round trip to your computer. Your servers' tools are then called like any other MCP tool. See the tool guide for naming, filtering and error handling.

Choose whether your AI can manage servers

Your configured, enabled servers' tools are always available. Adding, modifying, deleting, enabling or disabling server entries remotely requires explicit permission on your local Client:

mcp-relay config set admin true

Restart the Client to apply the change. To lock administration again:

mcp-relay config unset admin

Restart once more. Without it, the administration tools are not listed. This setting controls server administration, not the actions of tools exposed by your MCP servers. Configure those servers' permissions accordingly. Third-party results are relayed without scanning them for secrets.

Need help?

Use mcp-relay config show to inspect effective settings with secrets redacted. Logs are written to ~/.mcp-relay/server.log and client.log. The CLI guide covers configuration and diagnostics.

uv tool uninstall mcp-relay

Guides

CLI and configuration · Tools and server management · Security policy

Licensed under the MIT License.