Agent quickstart

This page is for AI agents. If you’re a person, use 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

pipx install merge-gateway

pip install merge-gateway also works. The command is mgw.

Sign up

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.

The output includes a claim URL. Show it to your user. Never print or paste the API key; --json output leaves it out.

Verify

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 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 <harness> \| --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:

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"

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 for other SDKs.

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

Harness-specific setup for Claude Code, Codex, Cursor, and others

Get started

Send requests with the OpenAI, Anthropic, or Vercel AI SDKs