Agent quickstart

This page is written for an AI agent. If you are a person, the Get started guide is shorter.

You are an agent running in a terminal (Claude Code, Codex, or similar) and your user wants their LLM traffic to go through Gateway. Nobody is around to open a browser. You can set everything up yourself in four commands, then hand your user one link.

Install the CLI

pipx install merge-gateway

Or pip install merge-gateway. The command is mgw.

Sign up as an agent

mgw agent signup

One call creates an organization with nobody in it, mints an API key for you, saves it under ~/.mgw (mode 0600), and writes your harness config: ~/.claude/settings.json inside Claude Code, ~/.codex/config.toml inside Codex. Pass --setup claude-code, --setup codex, or --no-setup to override the detection.

The output includes a claim URL. Show it to your user; do not paste the API key anywhere. Pass --json for machine-readable output (the key is excluded there too).

If you already signed up on this machine, signup refuses and points you at mgw agent whoami.

Confirm Gateway routes

mgw doctor

doctor checks the saved credential against Gateway and lists the models you can reach. Your harness now sends requests through Gateway with no further changes.

Hand ownership to your user

The organization you created is a sandbox until a person claims it: a small lifetime budget, a daily request cap, and a short list of inexpensive models. When you hit a limit, the error says so and tells you to have a human claim the organization.

Send your user the claim URL from signup. If it has expired or was lost:

mgw agent claim-url

This issues a fresh link and revokes the previous one. Your user opens it, creates an account or logs in, and becomes the organization’s admin. Your key keeps working before and after they do. Once they add a payment method and verify a phone number, the sandbox limits are lifted.

Commands

Command	What it does
`mgw agent signup [--setup T\|--no-setup] [--json]`	Create an organization and key, save credentials, write the harness config, print the claim URL
`mgw agent whoami [--show-claim-url] [--json]`	Show the organization behind the saved key and whether it has been claimed (validated with the server)
`mgw agent claim-url`	Re-issue the claim link (revokes the previous one)
`mgw agent forget`	Drop the local credentials and remove the key from harness configs (nothing is revoked server-side)
`mgw doctor`	Verify the credential and Gateway connectivity

Using the key directly

The saved key works like any Gateway API key. Read it from ~/.mgw/agent.json (api_key) and send requests to the gateway_url recorded alongside it:

curl https://api-gateway.merge.dev/v1/models \
  -H "Authorization: Bearer $MGW_API_KEY"

Gateway is OpenAI-compatible at /v1 and Anthropic-compatible at /v1/anthropic. See Get started for the SDKs.

Limits and abuse controls

Signup is unauthenticated, so it is rate limited per address and fleet-wide, and an address that already holds several unclaimed organizations must have one claimed before it can create another. A refusal comes back with a code and a message that says what to do; retrying in a loop will not help.

The organization you created has nobody in it. If it is still unclaimed after 30 days and has never been used, it is deactivated and the key stops working. mgw doctor will tell you to start over with mgw agent forget && mgw agent signup.

Behind a proxy or a non-production environment

Set MGW_CONTROL_PLANE_URL and MGW_GATEWAY_URL before signup to point both at another environment (for example https://api-gateway-develop.merge.dev). signup records the URLs it used, so later commands need no flags.

Next steps

Get started

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

Building with coding agents

Per-harness setup for Claude Code, Codex, Cursor, and more

Management API

Mint and revoke keys, manage projects and budgets once the organization is claimed

Cost governance

Budgets, spend caps, and what the sandbox limits become after a claim