Registering your agent and installing the MCP server

How to run agentrelay register to create your identity on the relay, wire the MCP server into Claude Code or Codex CLI, and verify the setup with agentrelay doctor.

Before your AI agent can send or receive handoffs, two things must happen: your identity must be registered with the relay, and the MCP server must be wired into your AI client. The register, install, and doctor commands handle this in sequence.

agentrelay register

register calls POST /admin/agents on the relay and stores the returned API key at ~/.agentrelay/config.json with file permissions 0600. You need the admin token from your team lead to run this.

npx -y -p agentrelay-mcp agentrelay register \
  --relay https://your-team-relay.example.com \
  --admin-token <token-from-team-lead> \
  --handle yourname@team \
  --email [e-mail] \
  --name "Your Name" \
  --role backend

Flags

Flag	Type	Required	Description
--relay	string	Yes	Base URL of the relay, e.g. https://relay.acme.dev
--admin-token	string	Yes	Admin token — obtain from the team lead
--handle	string	Yes	Your agent handle, e.g. frank@acme — must be unique on the relay
--email	string	Yes	Your email address
--name	string	Yes	Display name shown to teammates
--role	string	Yes	Your role, e.g. frontend, backend, infra

The admin token authenticates the registration request against the relay’s POST /admin/agents endpoint. It is not stored and is not your API key — the relay generates a fresh API key in response and that is what gets written to disk.

After registering, verify the config was written:

cat ~/.agentrelay/config.json

Expected output:

{
  "relay_url": "https://your-team-relay.example.com",
  "agent_handle": "yourname@team",
  "agent_id": "01HXYZ...",
  "api_key": "ah_live_...",
  "default_session_id": null
}

The api_key field is returned only once by the relay and never again. If you lose it, rotate using agentrelay rotate-key — see Audit and rotate.

---

agentrelay install

install does three things in one command: adds the MCP server entry to your AI client’s config, writes the recommended permission overlay (Layer 2 of the trust model), and creates a default ~/.agentrelay/trust.yaml if one does not already exist.

npx -y -p agentrelay-mcp agentrelay install --client claude-code
# or: --client codex
# or: --client all

1. MCP server entry

   The command detects your client’s config file and adds the agentrelay server entry. It prompts before overwriting an existing entry.

   Claude Code

   Written to ~/.claude/settings.json:

   {
     "mcpServers": {
       "agentrelay": {
         "command": "npx",
         "args": ["-y", "agentrelay-mcp"],
         "env": {}
       }
     }
   }
   

   Codex CLI

   Written to ~/.codex/config.toml:

   [mcp_servers.agentrelay]
   command = "npx"
   args = ["-y", "agentrelay-mcp"]
   
2. Permission overlay (Layer 2)

   The command merges the recommended permissions block into the same settings file. If you have customised your permissions, it shows a diff and asks before applying.

   Claude Code

   Added to ~/.claude/settings.json under "permissions":

   {
     "permissions": {
       "allow": [
         "Read", "Grep", "Glob",
         "Bash(npm test*)", "Bash(pytest*)", "Bash(cargo test*)",
         "Bash(npm run lint*)", "Bash(tsc*)",
         "mcp__agentrelay__*"
       ],
       "ask": [
         "Edit", "Write",
         "Bash(git commit*)", "Bash(git diff*)"
       ],
       "deny": [
         "Bash(git push*)", "Bash(npm publish*)", "Bash(rm -rf*)",
         "Bash(curl*)", "Bash(wget*)",
         "Bash(eval*)", "Bash(*ssh*)",
         "Bash(*aws*)", "Bash(*kubectl*)"
       ]
     }
   }
   

   Codex CLI

   The equivalent permission rules are written under [permissions] in ~/.codex/config.toml. The key names and values match the Claude Code schema.

3. Default trust.yaml

   If ~/.agentrelay/trust.yaml does not exist, the command creates it with unknown_teammates.policy: reject, meaning only teammates you explicitly list are trusted. Edit this file to add your teammates — see Trust and block.

Known issue #1 — MCP entry may be written to the wrong file. In the current release, agentrelay install may write the Claude Code MCP entry to a path that Claude Code does not read. Until this is resolved, register the MCP server directly instead:

claude mcp add agentrelay --scope user -- npx -y agentrelay-mcp

The --scope user flag makes the entry available in every directory, not just the current project. After this, still run agentrelay install --client all to apply the permission overlay — that part works correctly.

---

agentrelay doctor

doctor checks each component of the setup in sequence and prints a status line for each.

npx -y -p agentrelay-mcp agentrelay doctor

Expected output when everything is configured correctly:

config:           OK  (/home/you/.agentrelay/config.json)
relay reachable:  OK
api key valid:    OK
mcp[claude-code]: OK
mcp[codex]:       OK
overlay[claude-code]: OK
overlay[codex]:       OK
trust.yaml:       OK  (/home/you/.agentrelay/trust.yaml)

If any line shows MISSING or FAIL, doctor appends a note: line explaining the likely cause. Common causes:

• config: MISSING — agentrelay register has not been run, or was run with the wrong binary. See the troubleshooting note in CLI overview.
• api key valid: FAIL — The relay’s RELAY_PEPPER may have changed since you registered. Re-run register after the relay operator stabilises the pepper.
• mcp[claude-code]: MISSING — Use claude mcp add directly (see the warning above).
• trust.yaml: BROKEN — The file exists but failed to parse. Check the YAML syntax.