API tokens and MCP

Everything Ray can do, your own tools can do too. A personal access token lets a script, an editor or an agent call Relay as you, and a scope on the token says how much of you it gets to be.

Creating a token

1. Open API access

   Settings → Account → API access, then New token.

2. Name it and choose scopes

   Name the token after what will use it (snakemake on the cluster, Claude Code on my laptop). Tick the scopes it needs and nothing more. A read-only token cannot start a job or stop a run, whatever the caller asks.

3. Copy it once

   The token is shown a single time. Relay stores only a hash, so a lost token is revoked and replaced, never recovered.

Tokens look like rly_…. Revoke one from the same page; the caller gets a clear “not authenticated” from its next request.

Scopes

Read

jobs:read, assets:read, workspaces:read, pipelines:read, notebooks:read, schedules:read, models:read, compute:read, teams:read, comments:read, annotations:read, commons:read.

Write and run

jobs:write, assets:write, workspaces:write, pipelines:write, pipelines:execute, notebooks:write, notebooks:execute, schedules:write, comments:write, annotations:write, teams:admin.

Workspace control

app:control lets a caller open, split and focus panes in a tab you have open. It is how an agent can put a file in front of you.

Ray runs

Listing and reading your Ray runs needs jobs:read; stopping one needs jobs:write.

Relay checks a scoped token against every request it makes. Anything its scopes do not cover is refused with a 403 naming the scope it needs, and some parts of Relay (your account, billing, and token settings among them) are closed to scoped tokens altogether. Use a token with no scopes ticked for those.

Warning

A token acts as you and sees what you see. Do not paste one into a shared notebook, a repository, or a chat. Put it in an environment variable or a secrets store, and give each caller its own token so one can be revoked without breaking the others.

Using Relay from an AI coding tool (MCP)

Relay ships a Model Context Protocol server, so tools such as Claude Code, Claude Desktop and Cursor can read your jobs, open your files, run pipelines and notebooks, and hand you a workspace link, all through the same permissions as a token.

claude mcp add relay -- npx -y @relay-science/mcp
export RELAY_API_URL=https://relaysci.com
export RELAY_API_TOKEN=rly_…

The catalog has around 165 tools. A few worth knowing by name:

• relay_status answers who am I and what can this token do. Ask for it first when something returns 401 or 403.
• search_assets, resolve_project and probe_asset find and inspect your data.
• run_pipeline, run_notebook, watch_job start work and wait for it.
• list_ray_runs, get_ray_run and cancel_ray_run see and stop Ray’s own runs.
• get_app_link and the app_* tools open results in a tab you have open.

Note

The MCP server runs wherever the client runs. A tool argument called local_path reads that machine’s disk, which is only yours when the server is on your laptop; from a remote agent, pass content_base64 or source_url instead.

Tip

The same package installs a relay command line for shells, Makefiles, cron and CI.

Ray in Slack

Ray can also answer in Slack. Settings → Plan & usage → Integrations has an Add to Slack card: approve it in Slack, then tick the channels Ray may answer in. Ray stays quiet in every other channel, always acts as the person who asked, and only ever sees what that person can see. Slack runs appear in your Ray activity alongside the ones from the chat bar.