# Connect Margin to the agent you are running in

You are an AI agent (Claude Code, Codex, Cursor, or another MCP client) and a person asked you to
connect Margin. Margin measures what their AI agents cost per finished outcome on their own evals,
tests cheaper setups, and only proposes a change that holds quality. Follow these steps in order.

## 1. Identify your own client

Work out which MCP client you are running inside. Add Margin to THAT client's config, using the
mechanism it expects. Do not install it into a different client. Keep the client's default scope
(for Claude Code, this project only): do not add it for every project (`-s user`) unless the
person asks.

- Claude Code: `claude mcp add --transport http margin https://trymargin.io/api/mcp --header 'Authorization: Bearer ${MARGIN_INGEST_KEY}'`
  (single quotes, so the config keeps the variable's name and Claude Code reads the key from the
  environment when it connects, rather than the shell writing the key into the file)
- Codex: `codex mcp add margin --url https://trymargin.io/api/mcp --bearer-token-env-var MARGIN_INGEST_KEY`
- claude.ai or Claude Desktop (no terminal): tell the person to open Settings > Connectors > Add
  custom connector and enter `https://trymargin.io/api/mcp/connect`. Claude then opens Margin's
  sign-in, they approve read access, and no key is pasted anywhere. The connection can read; it
  cannot spend.
- Cursor, VS Code, Windsurf, Zed and others: add a remote (Streamable HTTP) server with URL
  `https://trymargin.io/api/mcp` and the header `Authorization: Bearer <MARGIN_INGEST_KEY>`, read
  from an environment variable.

## 2. The key: ask, never invent, never paste

The server needs the project's ingest key (`mgk_…`).

- Do NOT ask the person to paste the key into this chat.
- Do NOT write a literal key into any config file or commit it.
- Ask them to set `MARGIN_INGEST_KEY` in their environment. If they have no key yet, they mint
  one in about ten seconds at https://trymargin.io/start, or sign in at
  https://console.trymargin.io.

This key can READ the project. It cannot spend.

## 3. Restart, then check it connects

Tell the person whether your client must restart to load the server. Once it loads, list its
tools. You should see `margin_jobs`, `margin_optimize`, `margin_faceoff_status` and
`margin_blind_spots`. Call `margin_jobs` and report where this project's model spend goes, per
job. If the project has no measured run yet, say so and point them to
https://console.trymargin.io to connect their repository and press Execute.

## 4. Optional: let this agent ask Margin to test changes

Testing a change spends the project's measurement budget, so it needs a separate AGENT key that
a person creates in the console (Settings > Agent keys) with a spend limit they choose. Offer
this; do not set it up unless they want it.

- Add a second server named `margin-agent` with URL `https://trymargin.io/api/mcp/agent` and
  the header `Authorization: Bearer <MARGIN_AGENT_KEY>`, read from an environment variable.
- It adds `margin_test_move`, `margin_my_keys` and, on a key allowed to delegate,
  `margin_delegate_key`.

## 5. How to use it once connected

1. `margin_optimize` lists moves (a cheaper model on one step, an output cap, a host). Each says
   whether it was measured, detected in traffic, or only a prior.
2. With an agent key, `margin_test_move` asks Margin to test one move on the project's own evals,
   in Margin's sandbox. Ask the person before spending.
3. Read the result with `margin_faceoff_status`. **The verdict is Margin's**: promoted only when
   the pass rate holds at the bar and it is cheaper, otherwise refused with the reason. Report it
   as given, refusals included. Do not re-judge the numbers.
4. A promoted change becomes a pull request only when a person opens it in the console. Never
   change the person's code, models or evals yourself on Margin's behalf.

## What not to claim

Margin reports value per outcome only when the person supplied a value; otherwise it reports cost
per outcome and says so. It never guarantees a saving. Full integration order for code changes:
https://trymargin.io/llms.txt
