Relay

com.relaygpuPublished by relaygpu.comOfficial publisherv0.1.8Updated Oct 25, 2026

Run any Relay model (image, video, audio, LLM), poll tasks, upload files and search Relay's docs.

VerifiedStreamable HTTPWeb executableFinanceMedia & DesignAI & ML

Overview

AI-generated overview

Relay lets an assistant find, price and run hosted image, video, audio and text models, poll long tasks, upload files, run multi-step workflows and search its

What you can do
Search and inspect models: find models by tag or text, read a model's route, input schema, example request, pricing and availability, and search the bundled docs offline. Estimate spend: read list prices, including media-storage SKUs, and estimate the USD cost of a call. Run models: execute any Relay model by name, poll long-running tasks, and upload image, video or audio files to get URLs for model inputs. Workflows: list multi-step templates, start a run, poll it and cancel it between steps. Account: read credit balance, promos and per-key usage and spend.
When to use it
Useful when you want an assistant to generate or process images, video, audio or text through Relay's hosted models without writing API calls, and to check prices and estimate cost before running anything. Also fits multi-step pipelines such as script to voiceover, and looking up Relay's own documentation.
Requirements
Either the hosted endpoint at mcp.relaygpu.com, which needs no install, or the local npm package run with npx on Node 20 or newer. A Relay API key is required, passed as the X-API-Key header on the hosted server or the RELAY_API_KEY environment variable locally. Account tools get_credits and get_usage need a dashboard JWT or a custom-tier superkey instead of a plain key. Network access to Relay is needed.
Before you install
Running models and workflows is billed to your key, and each workflow step bills as an ordinary request; cost estimates are not invoices. Cancelling a workflow only stops it between steps, so a step already running still completes and bills. Result links expire after about an hour unless paid storage is set. The hosted server cannot read local files, so uploads go through a one-time slot, base64 or a public URL. The key grants spending on your account, so keep it out of shared configs and logs.

Installation

In SourceWeft

  1. Open Relay in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/com.relaygpu%2Fmcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

{
  "mcpServers": {
    "relay": {
      "type": "http",
      "url": "https://mcp.relaygpu.com/mcp"
    }
  }
}

README

@relaygpu/mcp

Relay's MCP server. Your agent can find a Relay model, read its input schema, run it, poll long tasks, upload files, run workflows and search the Relay docs, all from Claude Code, Cursor, VS Code or Claude Desktop. It is built on @relaygpu/client. The tools are generic and take the model as a string, so a model added to Relay works without a new release.

Connect to the hosted server, or run it locally:

HowCredential
Hosted (Streamable HTTP)https://mcp.relaygpu.com/mcp, nothing to installX-API-Key: relay_sk_... header, or Authorization: Bearer <relay key or dashboard JWT>
Local (stdio)npx -y @relaygpu/mcp (Node ≥ 20)RELAY_API_KEY=relay_sk_... in its environment; optional RELAY_BASE_URL (default https://relaygpu.com)

The server never stores your key: the hosted one reads it from each request and uses it for that request only, the local one reads it from its environment.

Install

Claude Code, Codex, Cursor and VS Code connect to the hosted server: no Node, no npx. Claude Desktop accepts remote servers only through OAuth, which v0 does not offer yet, so it uses the local server through a one-click bundle. Every client can also run the local server; see Local server.

Claude Code

Terminal, in the CLI or the VS Code / JetBrains extension alike:

bash
claude mcp add --transport http --scope user relay https://mcp.relaygpu.com/mcp --header "X-API-Key: relay_sk_..."

--scope user makes it available in every project; without it the server exists only in the directory you ran the command in. Check it with /mcp in a new session. If the terminal answers command not found: claude, the extension is installed but the CLI is not: install it with curl -fsSL https://claude.ai/install.sh | bash (or npm install -g @anthropic-ai/claude-code).

Codex

Codex sends the key as a Bearer token from an environment variable, so the key stays out of config.toml. Set RELAY_API_KEY in your shell profile, then:

bash
codex mcp add relay --url https://mcp.relaygpu.com/mcp --bearer-token-env-var RELAY_API_KEY

Cursor

[Add relay MCP server to Cursor]

The button installs the entry below with a placeholder key; replace relay_sk_... in Cursor's MCP settings afterwards. By hand: ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).

json
{  "mcpServers": {    "relay": {      "url": "https://mcp.relaygpu.com/mcp",      "headers": { "X-API-Key": "relay_sk_..." }    }  }}

VS Code (Copilot agent mode)

This installs the server for VS Code's own agent (Copilot Chat). Using Claude Code inside VS Code? Use the Claude Code command instead: the Claude Code extension does not read VS Code's MCP config.

[Install in VS Code]

VS Code asks for the key once and keeps it in its secret storage. By hand, in .vscode/mcp.json (one workspace) or with MCP: Open User Configuration (every workspace):

json
{  "inputs": [{ "type": "promptString", "id": "relay-key", "description": "Relay API key (relay_sk_...)", "password": true }],  "servers": {    "relay": {      "type": "http",      "url": "https://mcp.relaygpu.com/mcp",      "headers": { "X-API-Key": "${input:relay-key}" }    }  }}

Claude Desktop

  1. Download relay.mcpb.
  2. Double-click it. Claude Desktop opens an install dialog: click Install.
  3. The extension installs switched off. Open Settings → Extensions → Relay → Configure.
  4. Paste your Relay key and click Save. The key stays in Claude Desktop's secure storage.
  5. Switch Relay on.

The bundle runs on Claude Desktop's built-in Node, so nothing else needs to be installed. get_credits and get_usage read the account, so they take a dashboard JWT or a custom-tier superkey, never a plain key; every other tool works with a plain key.

By hand instead: Settings → Developer → Edit Config opens claude_desktop_config.json in your default editor. Add the block below at the top level, save, then quit Claude Desktop (⌘Q) and reopen it:

json
{  "mcpServers": {    "relay": {      "command": "npx",      "args": ["-y", "@relaygpu/mcp"],      "env": { "RELAY_API_KEY": "relay_sk_..." }    }  }}

Local server (stdio)

Any client can run the server on your machine instead; it needs Node 20 or newer on the PATH the client sees (see Troubleshooting).

bash
claude mcp add relay --scope user --env RELAY_API_KEY=relay_sk_... -- npx -y @relaygpu/mcpcodex mcp add relay --env RELAY_API_KEY=relay_sk_... -- npx -y @relaygpu/mcp

Cursor (~/.cursor/mcp.json) and VS Code take the same command / args / env entry as the Claude Desktop block above; VS Code adds "type": "stdio" and lists it under "servers".

Ready-to-copy files are in examples/.

Troubleshooting

  • "Server disconnected", "spawn npx ENOENT" or "Executable not found: npx" (Claude Desktop, Cursor). Apps opened from the Dock or Start menu do not load your shell profile, so a Node installed with nvm, Volta or Homebrew is not on their PATH. Use the Claude Desktop bundle, or put the full path in "command": run which npx in a terminal and paste the result (for example /Users/you/.nvm/versions/node/v22.22.0/bin/npx).
  • TypeError: Relay: no global fetch: the client started Node 16 or older. Install Node 20 or newer, or point "command" at a newer npx.
  • Windows: if the client cannot start npx, use "command": "cmd" with "args": ["/c", "npx", "-y", "@relaygpu/mcp"].
  • The first start takes a few seconds: npx downloads the package once (about 5 s); later starts take about 1 s.

Tools

Tools marked keyless work without a credential on the local server. Keyless tools answer the public catalog; with a credential, search_models, get_model, get_pricing, estimate_cost and run_model's model lookup answer your account's: the models your tier and grants can run appear and run. The others are billed or account tools and need one. A hosted server with OAuth on (see Self-hosting) takes no request without a credential, keyless tools included.

ToolWhat it doesExample
search_models keylessFind models by tag and/or text; image-to-image also lists every image model that takes an input image (accepts: ["image"])"Find a text-to-video model from Kling" → {tag: "text-to-video", query: "kling"}
get_model keylessRoute, request schema, example, pricing and status of one model{model: "Qwen/qwen-image"}
get_pricing keylessPrices (public; your account's with a credential) for one model or all of them, including the media_storage SKUs{model: "KlingTeam/v3-T2V"}
estimate_cost keylessEstimate from the price list (public; your account's with a credential; not an invoice){model: "KlingTeam/v3-T2V", usage: {duration_seconds: 5, quality_mode: "std"}}
run_modelRun any model by name and wait up to 45 s{model: "Qwen/qwen-image", input: {prompt: "a red fox", size: "512x512"}}
check_task keylessPoll a task (waits up to 30 s){task_id: "direct:…", wait_seconds: 30}
upload_fileHost a file and get a URL for any *_url input (or an image editor's image), or a one-time upload slot for a local file on the hosted server{path: "./clip.mp4", retention: "relay1d"} · {slot: true}
list_workflowsList the workflow templates"Which workflows can I run?"
run_workflowStart a workflow run, wait up to 45 s{workflow_id: "script-voiceover", inputs: {messages: [{role: "user", content: "a lighthouse at dusk"}], voice: "Cherry"}}
check_workflow_run keylessPoll a run (waits up to 30 s){run_id: "…", wait_seconds: 30}
cancel_workflow_runCancel a run that is still in progress{run_id: "…"}
get_creditsCredit balance, promos and consumption (JWT or custom-tier superkey)"How many credits do I have left?"
get_usageUsage analytics (JWT or custom-tier superkey){period: "7d"}
search_docs keylessSearch the Relay docs{query: "idempotency key"}

Local files

The hosted server cannot read files on your computer. How a local file reaches a model, per client:

ClientLocal file → model
Claude Code, Cursor, VS Code, Codex (hosted server)upload_file({slot: true}) returns a curl line; the agent runs it in your shell with the file's path (no key in the shell, single use, 10 minutes) and it prints the file's url; pass that url to run_model (for example as image).
claude.ai, Claude Desktop, ChatGPTupload_file({slot: true}) returns a link: open the link in your browser, pick the photo, and paste the link the page shows back into the chat; the model passes it to run_model. No key leaves the chat, single use, 10 minutes. A public URL of the file works too.
Local server (stdio), any clientupload_file({path: "./photo.png"}) uploads the file and returns its url.

Image editors: search_models({tag: "image-to-image"}) lists every image model that takes an input image, each with accepts: ["image"].

Notes

  • Auth. On the local server, and on a hosted server without OAuth, tools/list and the keyless tools answer without a credential. A hosted server with OAuth on answers every /mcp request without a credential with 401 and WWW-Authenticate: Bearer resource_metadata="…", scope="relay", which is how clients start the "Connect Relay" sign-in; X-API-Key and Authorization: Bearer <relay key or dashboard JWT> keep working there. A billed tool called without one returns a MISSING_CREDENTIALS tool error that names what to set: the X-API-Key header (hosted) or RELAY_API_KEY (stdio). Errors from Relay come back as tool errors that include the error class, code, requestId and the server's detail. Your key never appears in a tool result or a log line.
  • Long tasks. run_model waits up to 45 s (wait_seconds, 0–45). If the task is still running after that, it returns the task_id and the line "Do not resubmit: call check_task with this task_id". Every submit carries an Idempotency-Key, so a retry does not bill twice. Pass your own idempotency_key if your agent might send the same submit again. Since 0.1.7 every model whose input schema takes async (image, video, audio) is submitted as a task, so a long image run returns a task_id, never a 524; chat models still answer inline.
  • Expiry. Each result link comes with its expiry: "expires 1 h after completion unless store_output was set". To keep results longer, pass store_output with a media_storage SKU from get_pricing (for example relay7d). That SKU adds a per-file fee.
  • Image links. The image routes that answer base64 (Gemini, gpt-image, FLUX-2-pro) also answer Relay's own links (urls); the server returns those links in place of the base64, for 1 h or the store_output lifetime. A result that carries base64 without a Relay link is uploaded through /v2/files (at the store_output retention, else relay1h, free within the daily quota) and comes back as a URL and a file_id. Image content blocks are opt-in: pass inline_images: true, which applies to images of 1 MB or less.
  • Uploads. On stdio, upload_file streams a local path of up to 100 MB. The hosted server cannot read your disk: use slot: true (see Local files), base64 (up to 4 MB) or a public url. Retention defaults to relay1h.

Self-hosting

bash
docker build -t relaygpu-mcp .docker run -p 2300:2300 -e PORT=2300 -e RELAY_BASE_URL=https://relaygpu.com relaygpu-mcp

The server listens on PORT (default 2300) and calls Relay at RELAY_BASE_URL. Endpoints:

  • POST /mcp: Streamable HTTP, stateless.
  • GET /healthz: returns {status, version}.
  • GET /metrics: Prometheus text with mcp_tool_calls_total{tool,outcome} and mcp_tool_seconds{tool}.
  • GET /.well-known/mcp/server-card.json: the server and its tools.
  • GET /.well-known/oauth-protected-resource (and …/mcp): the RFC 9728 protected-resource metadata, only with OAuth on.

OAuth ("Connect Relay")

OAuth is on when both OAUTH_ISSUER and MCP_RESOURCE_URL are set; with either unset the server behaves as above (no metadata route, keyless tools answer without a credential). All three variables belong to the MCP app and are read once at start:

VariableProdStaging (VPN)Notes
OAUTH_ISSUERhttps://relaygpu.comhttps://staging-back-c54ef4a.opengpu.networkRelay's authorization server; the JWKS is read from {issuer}/v2/oauth/jwks, the exchange posts to {issuer}/v2/oauth/token
MCP_RESOURCE_URLhttps://mcp.relaygpu.com/mcphttp://relay-mcp-staging.internal.opengpu.network/mcpThis server's public /mcp URL: the access token's aud must equal it, and the metadata URL is its origin + /.well-known/oauth-protected-resource
OAUTH_MCP_CLIENT_SECRETsecretsecretThe relay-mcp client's secret: the same value as Relay's OAUTH_MCP_CLIENT_SECRET in the same environment, never shared across environments. Without it every exchange fails (503)

A Bearer value that is a JWT issued by OAUTH_ISSUER is an access token: the server verifies it (ES256 against the issuer's JWKS, aud, exp with 60 s skew), exchanges it at Relay for a 5-minute Relay credential and keeps that credential in memory per token hash until 30 s before it expires. A bad, expired or revoked token gets 401 with WWW-Authenticate: Bearer error="invalid_token", …; an authorization server that cannot be reached gets 503. Tokens, credentials and the secret are never logged.

Logs are JSON lines on stderr, WARNING and above by default (LOG_LEVEL). Without Docker, run npm ci && npm run build && node dist/http.js.

License

MIT

Source: README.md at commit 54b37af

Tools

14

search_models

Search Relay models

Lists Relay models by tag and/or text. Common tags: text-to-image, image-to-image, text-to-video, image-to-video, video-to-video, text-to-speech, speech-to-text, text-to-text, text-to-embedding. image-to-image also lists every image model that takes an input image. Returns name, tag, route and accepts (input media the model takes, e.g. ["image"]; [] for none) per model (at most 50). With a credential the list is your account's view (what its tier and grants can run), public otherwise. Then call get_model with a name for its input schema.

Parameterstagquery

get_model

Get a Relay model

Returns one model's route, request_schema (what run_model's input must follow), request_example, pricing and availability. With a credential the answer is your account's view (what its tier and grants can run), public otherwise. Then call run_model with an input shaped like request_example.

Parametersmodelrequired

get_pricing

Get Relay pricing

Returns Relay's list prices (USD), optionally for one model (with a credential your account's view: its tier and grants; public otherwise), plus media_storage: the per-file fees of the store_output / upload retention SKUs (relay1d, relay7d, …). Then estimate_cost for a number.

Parametersmodel

estimate_cost

Estimate a Relay cost

Estimates the USD cost of a call from the price list (with a credential your account's view: its tier and grants; public otherwise): an estimate, not an invoice (the bill uses provider-reported usage and any custom pricing on your account). Pass only the usage fields the model's billing_type (see get_model or get_pricing) reads: per_token: input_tokens, output_tokens, cached_input_tokens; per_image: image_count, resolution_tier; per_second_video: duration_seconds, quality_mode, sound; per_second_audio: duration_seconds; per_character: character_count; per_media_token: media_input_tokens, media_output_tokens. Add store_output / retention / file_count for storage fees.

Parametersmodelrequiredusagerequired

run_model

Run a Relay model

Runs any Relay model by name (billed to your key). input follows get_model's request_schema (request_example runs as is). Every model whose schema takes async (image, video, audio) is submitted as a task: it waits up to 45 s, past that it returns a task_id — do not resubmit, call check_task. Chat models answer inline. Result links expire 1 h after completion unless store_output names a media_storage SKU from get_pricing. Pass an idempotency_key if you may retry the same submit. Needs a Relay credential.

Parametersinputrequiredmodelrequiredstore_outputwait_secondsinline_imagesidempotency_key

check_task

Check a Relay task

Checks a task run_model returned (no key needed: the task_id is the capability). Waits up to 30 s for it to finish; returns the result when completed, else its status: then call check_task again, never resubmit. Task results are kept 1 h after they finish.

Parameterstask_idrequiredwait_secondsinline_images

upload_file

Upload a file to Relay

Hosts an image, video or audio file on Relay and returns its url: pass that url to any *_url input of run_model. Give exactly one of path (local server only, ≤ 100 MB), base64 (≤ 4 MB) or url (a public link Relay copies). retention: relay1h (default, free within a daily quota) or a media_storage SKU from get_pricing. Needs a Relay credential.

Parametersurlpathslotbase64filenameretention

list_workflows

List workflows

List Relay's workflow templates: multi-step pipelines (e.g. script → voiceover) run as one call. Each entry has workflow_id, input_schema and its steps (step_id + model). Run one with run_workflow; inputs follow input_schema.

Takes no parameters.

run_workflow

Run a workflow

Start a workflow run (one submit) and wait up to wait_seconds (≤ 45) for it to finish. Completed → the final output; still running → run_id: call check_workflow_run with it, never resubmit (a new run bills again). Each step is billed as an ordinary request. webhook_url gets ONE signed workflow.completed / workflow.failed delivery when the run ends. Get workflow_id and the inputs shape from list_workflows. Needs a Relay credential.

Parametersinputsrequiredwebhook_urlworkflow_idrequiredstore_outputwait_secondsidempotency_key

check_workflow_run

Check a workflow run

Poll a workflow run by run_id, waiting up to wait_seconds (≤ 30) for it to end. Completed → the final output; failed / cancelled → the error; still running → its steps so far: call check_workflow_run again. No key needed: the run_id is the access token.

Parametersrun_idrequiredwait_seconds

cancel_workflow_run

Cancel a workflow run

Cancel a workflow run. Cancels between steps only: a step already running completes and bills. A run that has already ended answers WORKFLOW_RUN_NOT_CANCELLABLE. Needs a Relay credential.

Parametersrun_idrequired

get_credits

Get credit balance

Read the account's credit balance, active promo credits and consumption. Needs a dashboard JWT or a custom-tier superkey; a plain inference key gets PERMISSION_DENIED (403). Needs a Relay credential.

Takes no parameters.

get_usage

Get usage

Read the account's usage and spend per API key, newest keys first, 10 keys per page (pass starting_after = the previous answer's next_cursor for the next page; limit up to 1000). Pass period (e.g. 7d, max 30d) for a by-date breakdown, or from + to. Needs a dashboard JWT or a custom-tier superkey; a plain inference key gets PERMISSION_DENIED (403). Needs a Relay credential.

Parameterstofromlimitperiodstarting_after

search_docs

Search the Relay docs

Search Relay's public docs (bundled, offline) for how-to, auth, errors, limits, retries, webhooks, files and pricing rules. Returns the best-matching sections: page, heading, docs path with anchor and an excerpt. For a model's input fields use get_model instead; to find a model use search_models.

Parameterslimitqueryrequired

Version history

5
  1. v0.1.8LatestOct 24, 2026
  2. v0.1.7Oct 15, 2026
  3. v0.1.6Oct 15, 2026
  4. v0.1.5Oct 15, 2026
  5. v0.1.4Oct 12, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts