Skip to main content
Glama
kxlion

MCP Relay

by kxlion
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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, macOS & Linux · Outbound connection · Your choice of MCP servers

CI PyPI Docker image License: MIT Python 3.14+

How it works · Get started · 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.

Your local MCP tools, available to your cloud AI

  • No inbound port. The Client on your computer connects out to the cloud Server and reconnects on its own after a network drop.

  • One endpoint for all your servers. Each local MCP server, stdio or Streamable HTTP, is published under a name you choose.

  • Native tools. Your servers' tools appear directly in your AI's tool list as <alias>_<tool>, such as localtools_read_file, and update when servers start, stop or change.

  • You decide what is exposed. Publish only the tools you allow per server; remote server management stays off unless you turn it on.

Alpha: one Server, one Client, one user. Configuration and the Server/Client contract may change between releases; see the release notes.

Related MCP server: webmcp-polyfill

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 AI agent calls one MCP endpoint on Relay Server. Relay Client, on your computer, carries each call to the right local MCP server and returns the result. The built-in relay_status tool reports the state of the whole chain.

Get started

You need a cloud AI agent that supports MCP over Streamable HTTP with an Authorization header, a cloud host reachable over HTTPS (a TLS reverse proxy or a secure tunnel), and your Windows, macOS or Linux computer. MCP Relay does not provide hosting, DNS or TLS.

1. Install

On the cloud host and on your computer:

uv tool install mcp-relay

No uv? The one-line installer sets it up first:

# Linux and macOS
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)

To read the installer before running it, or to pin a release, see Install and upgrade.

2. Create two tokens

Token

Shared by

RELAY_CLIENT_TOKEN

Server and Client

RELAY_MCP_TOKEN

Server and your AI agent

Use two different random values of 32–256 printable ASCII characters without spaces, for example from openssl rand -hex 32. Put them in ~/.mcp-relay/.env (%USERPROFILE%\.mcp-relay\.env on Windows), readable only by your user. See credentials.

3. Start the Server

On the cloud host, run mcp-relay onboard and choose Server only. Then route these two addresses through your TLS proxy, keeping the Authorization header and allowing long-lived WebSocket connections:

Public address

Internal destination

https://relay.example.com/mcp

http://127.0.0.1:8000/mcp

wss://relay.example.com/ws

http://127.0.0.1:8001/ws, with WebSocket Upgrade

mcp-relay config validate
mcp-relay server

For a proxy on another host or the Docker image, see the deployment guide.

4. Start the Client

On your computer, run mcp-relay onboard, choose Client connected to a remote Server and enter your wss://relay.example.com/ws address. MCP Relay bundles no MCP server: declare the ones you already use in ~/.mcp-relay/config.yaml:

mcp_servers:
  localtools:                   # an MCP server already running over HTTP
    url: http://127.0.0.1:9000/mcp
  browser:                      # a stdio MCP server launched by the Client
    command: [npx, "@example/browser-mcp"]  # placeholder package
    tools:                      # optional: publish only these tools
      navigate:
      screenshot:
        description: Capture the current page as a PNG.
mcp-relay config validate
mcp-relay client

Restart the Client after editing config.yaml.

5. Connect your AI agent

Setting

Value

Transport

Streamable HTTP

URL

https://relay.example.com/mcp

Header

Authorization: Bearer <RELAY_MCP_TOKEN>, kept in your agent's secret settings

Then ask it:

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

A live Client and your servers listed as running confirm the whole chain works. If not:

Symptom

Check

mcp-relay: command not found

Open a new terminal to pick up the updated PATH

Your AI gets 401 or cannot reach /mcp

The RELAY_MCP_TOKEN value and the proxy route to port 8000

client_unavailable

The Client is running, with the same RELAY_CLIENT_TOKEN as the Server, and /ws reaches port 8001

A server is missing or unavailable

Its error in relay_status, and client.log next to your configuration

mcp-relay config show prints the effective settings with secrets redacted. More in troubleshooting.

Want to try it first without a cloud host? Choose Local Server + Client during onboarding; see one computer.

Why MCP Relay?

You want to...

With a plain tunnel

With MCP Relay

Expose several MCP servers

One public URL and one auth setup per server

One endpoint; each server published under its own alias

Use stdio MCP servers

Needs a separate stdio-to-HTTP bridge

Launched and relayed by the local Client

Limit what the AI sees

Everything the server offers is exposed

Per-server tools: allowlist

Know whether your computer is reachable

Guess from timeouts

relay_status reports the whole chain

Survive network drops

Depends on the tunnel

The Client reconnects and the tool list updates itself

Tools such as mcp-remote solve the opposite problem, connecting a local MCP client to a remote server.

Security in brief

  • Both tokens stay out of YAML, command arguments and config show output.

  • The Server listens on loopback by default; keep it behind your TLS proxy.

  • Your AI can add, modify, enable, disable or delete server entries only after mcp-relay config set admin true on your computer.

  • MCP Relay relays the servers you configure; what their tools can do depends on those servers and their own permissions. Their results are relayed as is.

See the security policy to report a vulnerability.

Guides

Licensed under the MIT License.

Available Tools

2 tools
relay_statusRelay StatusA
Read-only

Report the Relay Server, the connected Client and its MCP servers.

Call it first to check that the Client is connected and which server aliases run, when a tool is missing or fails, and after an administration change. Read-only. Client details come from a short live probe; when the Client is busy or unreachable the last good answer is returned as cached with its age. To discover servers that are not configured yet, use relay_registry_search.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
clientYes
serverYes
mcp_serversYes
disk_differsYes

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the read-only safety profile, and the description goes further by disclosing the live-probe mechanism and the degraded-mode behavior: when the Client is busy or unreachable, a stale answer is returned flagged as ``cached`` with its age. That failure-mode/fallback semantics is exactly the context an agent cannot get from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, then triggers, then caveats, then the sibling pointer — a sensible order with no wasted padding. The standalone 'Read-only.' sentence slightly duplicates the readOnlyHint annotation, a minor redundancy in an otherwise tight description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no prose explanation. Coverage of purpose, invocation timing, degraded behavior, and the sibling alternative is complete for a no-argument status tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool applies. No parameter guidance is missing or needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and three concrete resources it reports on: the Relay Server, the connected Client, and its MCP servers. It also distinguishes itself from the sibling by contrasting configured server aliases with servers not yet configured.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit triggers: call first to confirm the Client is connected, when a tool is missing or fails, and after an administration change. It also names the alternative and the different need it serves ('To discover servers that are not configured yet, use relay_registry_search').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.1.1
    • Changedrelay_registry_search6 fields changed
      • addedInput schema / properties / cursor / description
        Added value: +"The next_cursor of a previous result; omit for the first page."
      • addedInput schema / properties / include_deleted / description
        Added value: +"Also return servers deleted from the registry."
      • addedInput schema / properties / limit / description
        Added value: +"Results per page, 1-50."
      • addedInput schema / properties / query / description
        Added value: +"Text matched against server names, 1-200 characters."
      • addedInput schema / properties / updated_since / description
        Added value: +"RFC 3339 timestamp: only servers updated since then, deleted entries included."
      • addedInput schema / properties / version / description
        Added value: +"'latest' or an exact server version."
  2. 2 tool updatesv0.1.0
    • First observedrelay_registry_search
    • First observedrelay_status
Deploy Server
Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

TDQS

A4.1/5.0

Scored across 2 tools

Disambiguation4/5

relay_status (report configured Client/servers) and relay_registry_search (discover unconfigured servers) have clearly distinct purposes, and each description explicitly redirects to the other for the complementary case. Only minor overlap in that both are read-only discovery/observability operations, but boundaries are unambiguous.

Naming Consistency4/5

Both tools use a consistent snake_case 'relay_' prefix, forming a predictable namespace. The suffix pattern is not strictly verb_noun (status vs registry_search), a minor deviation, but naming is coherent and readable.

Tool Count2/5

Only two tools for a server whose purpose (relaying/managing an MCP Client and its servers) implies administrative capability; the surface feels notably thin. Descriptions even reference actions like 'administration change' that no tool exposes.

Completeness2/5

A clear dead end exists: relay_registry_search returns a 'name' described as 'the source for adding that server,' yet there is no tool to add, remove, or invoke anything. Status and discovery are covered, but the core lifecycle implied by the domain is missing.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers