# Connect yourself to qr-relay

You are an agent, or the person driving one. qr-relay gives a physical thing a
permanent web address: the QR code someone prints never changes, and the
destination behind it stays editable forever.

The endpoint is ONE URL, and it speaks MCP over Streamable HTTP:

    https://qr-codes.ink/mcp

**There is no token to ask anyone for.** Authorization is OAuth 2.1 with WorkOS
AuthKit; you register the URL, and a browser opens for your human to sign in as
themselves. If a person offers you a qr-relay API key, something is wrong —
this service does not issue them.

## 1. Register the server in YOUR harness

Work out which harness you are running in and do its step yourself.

### Claude Code

```sh
claude mcp add --transport http qr-relay https://qr-codes.ink/mcp
```

Then run `/mcp` inside Claude Code and authorize. A browser opens, you sign in to qr-relay as yourself, and the agent can then do what your role allows in your workspaces — nothing more.

### Cursor

```json
{
  "mcpServers": {
    "qr-relay": { "url": "https://qr-codes.ink/mcp" }
  }
}
```

In `.cursor/mcp.json` (this project) or `~/.cursor/mcp.json` (everywhere).

### Codex CLI

```toml
[mcp_servers.qr-relay]
url = "https://qr-codes.ink/mcp"
```

Appended to `~/.codex/config.toml`.

### Anything else that speaks MCP

Streamable HTTP at `https://qr-codes.ink/mcp`, OAuth 2.1 with WorkOS AuthKit as the authorization server. Discovery is at `/.well-known/oauth-protected-resource`; the endpoint answers `POST` only, and is stateless — no session to open, no event stream to hold.

## 2. Authorize

Trigger the connection (in Claude Code, `/mcp`). A browser opens; your human
signs in to qr-relay and approves. The token that comes back is bound to them:
you can do exactly what their role allows in their workspaces, and no more.

## 3. Check what you can do

- `list_workspaces` — List the workspaces you belong to, with each one’s id, name and your role there. Call this first if you are not sure which workspace to act in, then pass its name or id as `workspace` to the other tools.
- `list_qr_codes` — List the QR codes in a workspace, with the address each one is printed with and where it currently points.
- `get_qr_code` — Look up one QR code in a workspace by its id or its slug, and report where it currently points.
- `create_qr_code` — Mint a new QR code in a workspace pointing at a destination, and return the value to print. By default the code is relayed: the printed address never changes and the destination stays editable. Pass kind "static" to print the destination directly into the pattern instead — nothing can change it afterwards and its scans are never counted. print_host chooses which address a relayed code carries: "workspace" (the default) uses the workspace’s own connected domain when it has one, "platform" pins the code to qr-codes.ink and needs a connected domain to mean anything different.
- `set_qr_destination` — Re-point an existing QR code in a workspace at a new destination. Anything already printed keeps working and starts leading to the new place within a minute.

If your human belongs to more than one workspace, call `list_workspaces`
first and pass `workspace` (its name or id) to every other tool. A call that
names none is refused with the list, never guessed; every result names the
workspace it acted in.

Reconnect after any change — MCP clients cache the tool list per session.

## 4. What to remember

A printed address is permanent. `create_qr_code` returns the URL to print, and
that URL can never be changed afterwards — so print what the tool returned,
never a URL you assembled yourself from a slug.

A destination is not permanent, and that is the point. `set_qr_destination`
re-points a code; everything already printed keeps working and starts leading
somewhere new within a minute.

You cannot delete or pause a code. That is deliberate, not a gap: retiring a
pattern already printed on physical goods is a decision with consequences you
cannot see. Send your human to their workspace for it.

Full docs: https://qr-codes.ink/docs (markdown at https://qr-codes.ink/docs.md)