Relay docs for real work

Everything you need to get Relay running

Relay is a local MCP server with 40 built-in tools in one Go binary. This page gets you from install to first useful prompt, then gives you the full tool map, CLI reference, config examples, and practical recipes.

Start with npx See all 40 tools
start here, then copy what you need
01 · Start here

Getting Started

Keep it simple. Install Relay, let it wire itself into your editor, then try one small prompt that proves the whole thing works.

Install

The main path is npx relay-mcp init. It is the quickest way to get the binary in place and set up your editor without hunting through docs.

Primary: npx relay-mcp init Secondary: curl + relay init Third: go install + relay init
Recommended
npx relay-mcp init

Runs the setup flow, installs what you need, and gets you to a working relay command fast.

Mac / Linux fallback
curl -fsSL https://relay.dev/install.sh | sh
relay init

Good if you want the direct installer path and then the same setup wizard.

Go fallback
go install github.com/valtors/relay@latest
relay init

Nice if Go is already part of your day and you want the raw binary straight from source.

Connect to your editor

relay init should handle this for you. If you want to wire it in manually, jump to the full JSON examples in Configuration.

  • Claude Desktop
  • Cursor
  • VS Code with MCP support
  • Any other MCP client that can run a local command

First run

When you start Relay, it boots the MCP server, loads the 40 tools, and waits for requests from your editor. By default it runs over stdio. If you start it with relay start --http, it exposes a local HTTP MCP endpoint instead.

  • Default transport: stdio
  • HTTP transport: http://127.0.0.1:8080/mcp by default
  • Files stay local unless you use the web tools

Your first task

Start with something tiny and obvious. You want a fast win, not a stress test.

Prompt 1
"Use Relay to count the words in README.md"

Fast proof that your editor can talk to Relay and call a tool.

Prompt 2
"List the files in this folder and summarize what this project is"

Good when there is no README around.

Prompt 3
"Resize every PNG in ./screenshots to 800px wide"

Shows off file tools plus image tools in one go.

One useful mental model

You do not need to think in tool calls. Just ask naturally. Relay gives your editor the hands. The model decides when to use them.

02 · All built-ins

Tools Reference

All 40 tools, grouped by category. Every card includes what it does, the params you need, and an example prompt you can actually try.

Heads up on workflow tools

The workflow tools are still building. They also need an ANTHROPIC_API_KEY to run the multi-step product workflow.

03 · Terminal commands

CLI Reference

Relay keeps the CLI small on purpose. Most people only use a handful of commands day to day.

relay

Start Relay in stdio mode

Runs the MCP server with the default transport. This is what most editor configs call behind the scenes.

relay
relay init

Run the setup wizard

Detects supported editors, patches the JSON config for you, and gives you a clean next step. This is the manual version of the npx relay-mcp init path.

relay init
relay start

Explicitly start the server

Same idea as relay, but useful when you want the intent to be extra clear or when you want HTTP mode.

relay start
relay start --http
relay start --http --addr :9090
relay tools

List available tools

Handy when you want to check what is loaded or inspect the output in JSON.

relay tools
relay tools --json
relay status

Quick health snapshot

Prints the current version, the number of registered tools, and the supported transports.

relay status
relay version

Print the current version

Exactly what it sounds like. Good for bug reports and support questions.

relay version
04 · Copy-paste setup

Configuration

If relay init already patched these files for you, great. If not, here are clean manual examples you can drop in as-is.

Claude Desktop

This is the usual shape for Claude Desktop. If you use workflow tools, add your API key under env.

{
  "mcpServers": {
    "relay": {
      "command": "relay",
      "args": [],
      "env": {
        "ANTHROPIC_API_KEY": "your-key-here"
      }
    }
  }
}

Cursor

Cursor uses the same basic idea. Put it in your global config or your project-level .cursor/mcp.json.

{
  "mcpServers": {
    "relay": {
      "command": "relay",
      "args": [],
      "env": {}
    }
  }
}

VS Code

VS Code MCP config uses a servers key in many setups. This is the shape you want.

{
  "servers": {
    "relay": {
      "command": "relay",
      "args": [],
      "env": {}
    }
  }
}

Generic HTTP mode

Start Relay in HTTP mode, then point any MCP client that supports Streamable HTTP at /mcp.

relay start --http --addr :8080

{
  "mcpServers": {
    "relay-http": {
      "transport": {
        "type": "streamable-http",
        "url": "http://127.0.0.1:8080/mcp"
      }
    }
  }
}

Environment variables

  • ANTHROPIC_API_KEY Required for the workflow tools.
  • CHECKPOINT_TIMEOUT_MINUTES Optional timeout for approval checkpoints.
  • MAX_ITERATIONS_PER_STAGE Optional cap for workflow retries.
ANTHROPIC_API_KEY=your_key_here
# CHECKPOINT_TIMEOUT_MINUTES=30
# MAX_ITERATIONS_PER_STAGE=5

HTTP mode setup notes

1

Start Relay

Run relay start --http or set a custom port with --addr.

2

Point your client at /mcp

The default endpoint is http://127.0.0.1:8080/mcp.

3

Keep Relay running

Unlike stdio mode, HTTP mode is a background service, so leave that terminal open or run it in a process manager.

05 · Real examples

Workflows / Recipes

These are the kinds of tasks Relay is good at right away. Exact prompts included. Copy them, tweak the paths, and go.

Workflow tools note

The product workflow commands are still building and need an API key. The recipes below focus on the stable built-in file, image, PDF, text, data, and web tools.

Recipe 1

Image batch processing

Prompt

"Take every PNG in ./screenshots, resize them to 1200px wide, convert them to JPEG, and save them in ./screenshots/processed"

Tools used

file_list → image_resize → image_convert → file_write if the client needs a summary file

Recipe 2

PDF data extraction

Prompt

"Read invoice.pdf, extract all text, then pull out every invoice total and return a JSON array"

Tools used

pdf_extract_text → text_extract_regex → data_json_format

Recipe 3

Web scraping to structured data

Prompt

"Fetch https://example.com/pricing, extract the plan names and prices, and return valid JSON"

Tools used

web_fetch → text_extract_regex or model parsing → data_json_format

Recipe 4

File organization

Prompt

"List the files in ./downloads, group them by type, then write a cleanup plan to ./downloads/cleanup-plan.md"

Tools used

file_list → file_size → file_write

Recipe 5

Data format conversion

Prompt

"Convert this CSV to JSON, grab the first customer's email, and give me both the full JSON and the extracted value"

Tools used

data_csv_to_json → data_json_query → data_json_format

06 · Common questions

FAQ

Short answers, no fluff.

Does it need internet?

No for the local tools. Yes only when you use the web tools, or the workflow tools that rely on an API-backed model.

Does it send my files anywhere?

No. Relay runs locally. File, image, PDF, text, and data operations happen on your machine.

What editors work?

Any MCP client. Claude Desktop, Cursor, VS Code, and anything else that can connect to an MCP server.

Can I add my own tools?

Yes. Relay is open source, and the repo includes guidance for adding tools and contributing.

Is it free?

Yes. MIT licensed, open source, and free to use.