Docs

Connect Claude to RelayWork

RelayWork exposes a Model Context Protocol server, so an agent can read a spec, push a document, attach the code it wrote and ask for review — in the same gates your team uses.

Setup

An admin mints a token in Settings → API tokens, choosing read or write scope. Tokens start with rw_, are shown once, and are stored only as a hash — losing one means minting another.

claude mcp add relaywork --transport http \
  https://api.relaywork.app/api/v3/relay/mcp \
  --header "Authorization: Bearer rw_your_token"

Any MCP client works — the endpoint is streamable HTTP JSON-RPC. Point your own client at the same URL with the same bearer header.

Then talk to it in plain language. Specs are addressable by reference, so “push this as the requirements for AC-24” is enough — no ids to copy.

The eleven tools

Tool	Arguments	What it does
list_specs	—	Every spec in the workspace: id, ref, title, gate state, bucket, status, owner, url.
get_spec	spec_id \| spec_title, kind	One document plus its version, status, open review notes, linked specs, code refs and build info.
pending_reviews	—	Everything currently waiting on a human reviewer.
list_tasks	spec_id?	Tasks, optionally scoped to one spec.
create_spec	title, description?	Creates a spec. Title ≤200 chars, description ≤2000.
update_spec	spec_id, title?, description?, bucket?, owner_email?	Edits the spec envelope, not its documents.
push_spec	spec_id \| spec_title, kind, markdown	Creates or replaces a requirements or implementation document. Enforces the house template, word limits and readability rules; editing an approved document bumps the version and returns it to review.
add_code_ref	spec_id, refs[{url, note, kind}]	Attaches GitHub permalinks to the spec. Up to 50 per call; each ref reports added, rejected or skipped.
request_review	spec_id, kind	Sends a document for review and notifies the reviewers.
create_task	title, spec_id?, type?, priority?	Creates a task, optionally under a spec.
update_task	task_id, status?, assignee_email?, …	Moves or edits a task.

Lime names need a write-scoped token. A read token can call the rest.

There is no approve tool

Not permission-gated, not admin-only — absent. An agent can draft, revise, attach code and request review. A human approves, in the app, with their name on it.

This is deliberate and it is the one part of the design we would not change. A capability that exists can be reached by a misconfiguration, a leaked token or a persuasive prompt; a capability that does not exist cannot. Machine writes are attributed to token:<name> rather than to a teammate, and documents an agent edited are marked as such in the UI.

Document templates

push_spec enforces these. A document missing most of its sections is rejected with the template it should have used.

# Requirements  (kind: "requirements", ≤900 words)
1. What's the problem?
2. What will be different when this ships?
3. What are we building?
4. What does it look like?
5. What are we NOT building?
6. How do we prove it works?
7. Any hard rules?

# Implementation  (kind: "design", ≤1400 words)
Approach
Data model
API
Failure modes
Test strategy
Slices          (each ≤2 days)
Rollout

Paragraph-length bullets are rejected too. The limits exist because generated prose is fluent and unreadable at volume, and a document nobody reads carefully launders a decision nobody made.

Attaching code

Do not paste code or links into the markdown. Attach it as refs — permalinks pinned to a commit, each with one line on why it matters — and RelayWork renders the source beside the document.

add_code_ref({
  spec_id: "AC-24",
  refs: [
    { url:  "https://github.com/acme/checkout-api/blob/1f30bb1/meter.go#L88-L112",
      note: "The write path. Atomic increment avoids read-modify-write races.",
      kind: "touched" },
    { url:  "https://github.com/acme/checkout-api/blob/1f30bb1/handlers.go#L60-L72",
      note: "Other upload path, untouched by this PR. Cloning a file now meters.",
      kind: "blast_radius" }
  ]
})
// → { added: [...], rejected: [...], skipped: [...] }

Each ref reports its own outcome, so one bad link cannot lose the rest of a batch. The same lines at a new commit count as a re-anchor, not a duplicate. See code ref and blast radius.

A session that works

1. get_spec       → read the approved requirements and any open review notes
2. (read the code, open a draft PR with stubs)
3. push_spec      → the implementation document, from what you found
4. add_code_ref   → the 3-6 places carrying the decisions
5. request_review → a human reads it and approves, or does not

Step 2 is the one agents skip and the one that matters: a plan written without reading the code describes a codebase that does not exist.

Machine-readable copies

/llms.txt carries this reference plus the practice in one file, and /llms-full.txt is the long version. Point an agent at either.