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 · Guides

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.

Related MCP server: Brainstorm

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.

Your AI discovers the available servers and tools through relay_mcp_list, then uses relay_mcp_command to call them. The remote endpoint exposes a fixed set of 10 Relay tools; third-party tools are discovered through those tools rather than appearing individually in the AI client's tool list.

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.

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.

Linux:

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

Windows:

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

These settings belong in the Server environment or private .env, not YAML:

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

The listener addresses must be distinct. If the proxy is on another host, choose private bind addresses it can reach and restrict access with a firewall.

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. 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:

Check my connection with relay_client_status, then use relay_mcp_list to discover the MCP servers and tools available on my computer.

A successful Client status call checks the round trip to your computer. To use a discovered tool, the AI calls relay_mcp_command with the catalog_revision returned by discovery. See the tool guide for the full request formats.

Choose whether your AI can manage servers

Discovery and tool execution are available for your configured, enabled servers. 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. 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.

Yes. Choose Local Server + Client during onboarding. The MCP endpoint defaults to http://127.0.0.1:8000/mcp, and the Client connects to ws://127.0.0.1:8001/ws. Both tokens are still required. A cloud AI agent cannot reach your computer through these loopback addresses.

Stop the Relay processes on the machine, then run:

uv tool uninstall mcp-relay

Your configuration, private .env and workspace under ~/.mcp-relay are preserved. Data removal is a separate manual step.

Guides

CLI and configuration · Tools and server management · Security policy

Licensed under the MIT License.