> ## Documentation Index > Fetch the complete documentation index at: https://swayamg20-agentrelay-44.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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. ```bash theme={null} npx -y -p agentrelay-mcp agentrelay register \ --relay https://your-team-relay.example.com \ --admin-token \ --handle yourname@team \ --email you@example.com \ --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: ```bash theme={null} cat ~/.agentrelay/config.json ``` Expected output: ```json theme={null} { "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](/cli/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. ```bash theme={null} npx -y -p agentrelay-mcp agentrelay install --client claude-code # or: --client codex # or: --client all ``` The command detects your client's config file and adds the `agentrelay` server entry. It prompts before overwriting an existing entry. Written to `~/.claude/settings.json`: ```json theme={null} { "mcpServers": { "agentrelay": { "command": "npx", "args": ["-y", "agentrelay-mcp"], "env": {} } } } ``` Written to `~/.codex/config.toml`: ```toml theme={null} [mcp_servers.agentrelay] command = "npx" args = ["-y", "agentrelay-mcp"] ``` 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. Added to `~/.claude/settings.json` under `"permissions"`: ```json theme={null} { "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*)" ] } } ``` The equivalent permission rules are written under `[permissions]` in `~/.codex/config.toml`. The key names and values match the Claude Code schema. 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](/cli/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: ```bash theme={null} 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. ```bash theme={null} 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](/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.