> This page is for Gateway. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # Sign up for an LLM gateway as an AI agent > How an AI coding agent signs up for Merge Gateway with the mgw CLI, routes its harness through Gateway, and hands its user a claim link. This page is for AI agents. If you're a person, use [Get started](/merge-gateway/get-started). You are an agent in a terminal (Claude Code, Codex, or similar), and your user wants their model traffic to go through Gateway. You can create an account, get a key, and configure your harness yourself, then hand your user one link to take ownership. #### Install the CLI ```bash brew install pipx # macOS, if you do not have pipx pipx install merge-gateway ``` The command is `mgw`. Homebrew Python refuses a bare `pip install` with `externally-managed-environment`, so install pipx first on macOS. #### Sign up ```bash mgw agent signup ``` This creates an organization with no members, mints an API key, saves it to `~/.mgw/agent.json` (mode `0600`), and points your harness at Gateway: `~/.claude/settings.json` in Claude Code, `~/.codex/config.toml` in Codex. Override detection with `--setup claude-code`, `--setup codex`, or `--no-setup`. Add `--json` for machine-readable output. > **\`--setup\` writes a machine-wide config** > > Both `~/.claude/settings.json` and `~/.codex/config.toml` apply to every project on the machine. The default run sends all of your user's existing model traffic to the new sandbox organization, which has a \$1 lifetime budget. Run `mgw agent signup --no-setup` when your user already has a configured harness, then set the credential where you want it. The output includes a **claim URL**. Show it to your user. Never print or paste the API key; `--json` output leaves it out. #### Verify ```bash mgw doctor ``` `doctor` checks the saved key against Gateway and reports how many models it can reach. After this, your harness sends its requests through Gateway. #### Hand ownership to your user Until a person claims it, the organization is a sandbox: | Limit | Value | | --------------- | ------------------------------------------------------------------------ | | Lifetime budget | \$1 | | Requests | 15 per day | | Models | `openai/gpt-5-nano`, `google/gemini-2.5-flash-lite`, `amazon/nova-micro` | | Claim link | Valid for 7 days | A request past a limit fails with a message telling you to have a person claim the organization. Your user opens the claim URL, signs up or logs in, and becomes the organization's admin. Claiming moves the organization onto the same plan and limits as a normal signup. The agent key keeps working, but it keeps its \$1 spend limit, so your user should raise that limit or mint a new key on the [API keys](https://gateway.merge.dev/api-keys) page. A person who already belongs to a Gateway organization can't claim a second one. They should mint a key in their existing organization instead. ## Commands | Command | What it does | | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `mgw agent signup [--setup \| --no-setup] [--json]` | Create the organization and key, save credentials, configure the harness, print the claim URL. Refuses if you already signed up on this machine | | `mgw agent whoami [--show-claim-url] [--json]` | Show the organization behind the saved key, whether it's claimed, and the saved claim URL | | `mgw agent claim-url` | Issue a new claim URL and revoke the previous one | | `mgw agent forget` | Delete local credentials and remove the key from harness configs. Nothing is revoked on the server | | `mgw doctor` | Check the credential and connectivity | ## Use the key directly The saved key is a normal Gateway API key. Read `api_key` from `~/.mgw/agent.json`, export it, and call Gateway at the `gateway_url` saved next to it: ```bash export MERGE_GATEWAY_API_KEY="$(python3 -c 'import json,os;print(json.load(open(os.path.expanduser("~/.mgw/agent.json")))["api_key"])')" curl https://api-gateway.merge.dev/v1/models -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" ``` The compatible listings return the full catalog rather than what your key can reach: `/v1/openai/models` returned 278 models and `/v1/anthropic/v1/models` returned 273 in October 2026, while a sandbox organization can call only the three in the limits table above. `/v1/models` is the one that reflects your access, returning only the models you can call, each with an `availability_status`. Gateway returns a 403 at call time for any model outside that set, so prefer `/v1/models` when picking one, or run `mgw doctor` to see how many models the key can reach. Use `https://api-gateway.merge.dev/v1/openai` as the base URL for OpenAI clients and `https://api-gateway.merge.dev/v1/anthropic` for Anthropic clients. See [Get started](/merge-gateway/get-started) for other SDKs. ## Signup limits Signup is rate limited to 3 per hour per IP address. An address holding 3 unclaimed organizations from the last 30 days must get one claimed before creating another. A refused signup returns a `code` and a message saying what to do. Retrying won't help. An unclaimed organization with no spend after 30 days is deactivated, and its key stops working. `mgw doctor` then tells you to run `mgw agent forget && mgw agent signup`. ## Next steps #### [Coding agents](/merge-gateway/coding-agents/overview) Harness-specific setup for Claude Code, Codex, Cursor, and others #### [Get started](/merge-gateway/get-started) Send requests with the OpenAI, Anthropic, or Vercel AI SDKs