# Access, scope and keys

- [Connections](#connections)
- [Agent scope](#agent-scope)
- [Product keys](#product-keys)
- [Live approval](#live-approval)

## Connections

| Setup                                             | MCP                                                                                         | CLI                                |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------- |
| `hyperscale agent setup <host>`                   | `.mcp.json` sends an `Authorization` header that reads the agent token from the environment | The same token is the login        |
| `agent setup <host> --oauth`, or `claude mcp add` | The host runs browser OAuth on first use                                                    | A separate `hyperscale auth login` |

Both reach `https://hyperscale0.ai/v1/mcp`. The agent token works in sandbox only and covers creating
and planning Products, test customers, funding, actions and the clock. Its tools take no `tenantId`;
the server fills it, and a different one returns `tenant_mismatch`. `hyperscale whoami --json` names
the credential in use and nests the founder's role under `founder`: you act within that role and are
not the owner.

Never edit the MCP entry, read credential files, env files, shell history or the Keychain, or ask for
a token in chat. When your token stops working, the refusal says why. `agent_token_replaced` means
the founder re-ran `agent setup`; `agent_token_expired` means the grant ended. Both put the founder's
command in `details.nextStep`. Give it to them and ask them to restart you; don't retry, and don't
ask for wider scope.

The founder's own CLI login:

- Browser: `hyperscale auth login --no-open --json` with a 10-minute tool timeout. Give the founder
  the URL and code it prints. A rerun resumes the pending request.
- No browser, existing account: pipe the password on stdin to
  `hyperscale auth login --email <email> --json`, then `auth login --code <code> --json` with the
  emailed six-digit code.
- No account: pipe the password to
  `hyperscale auth signup --email <email> --name <name> --company <company> --json`, then
  `auth signup --code <code> --json`.

## Agent scope

An agent sees and acts on the Products it created and the ones the founder named with
`--product <id>`; `--all-products` gives it every sandbox Product. MCP and the CLI share the scope.

- `agent_member_current` and `product_list` show those Products. When some are left out, `nextStep`
  carries the founder's command: `hyperscale agent setup --name '<agent>' --product <productId>`.
- Customers, accounts, activity, transfers and the money summary need a `productId`.
- A call on another Product returns `unauthorized`, names it, and puts the founder's command in
  `details.nextStep`. The CLI prints it as Next. Show it to the founder; don't work around it.
- Company records with no `productId` are refused outright: treasury, safeguarding, statements,
  statement exports, usage statements and company profile changes.
- You attach a customer to your Product only if you created that customer or it already uses one of
  your Products.

Re-running `agent setup` with the same name replaces the token and keeps the Products. `--product`
adds one and `--remove-product` takes one off.

## Product keys

MCP never returns a credential. A key tool answers with the CLI command, which you run with your own
token:

```bash
hyperscale key create --product <productId> --name <name>
```

The CLI shows the key once. If you have no shell, give the founder the command. A Product created
over MCP or the CLI returns `key_delivery: "unavailable"`, because only the Build portal's browser
session gets the start key. Live keys come only from the founder with `hyperscale key create-live`.

A Product key set in the environment wins over the agent token for Product commands. When it belongs
to another Product, the CLI refuses and names the variable to unset.

## Live approval

Every live action, reads included, needs the founder's fresh approval in the browser. A call that
returns `agent_approval_required` carries a link: show it and wait. The founder approves with their
password; a chat reply, a host confirmation or `--yes` cannot approve it. Approval binds
the operation, its arguments, Product, Build, revisions and idempotency key, and expires after ten
minutes. Resume with `hyperscale api resume <reference> --json`, or retry the same call with the same
idempotency key, and check the receipt. Don't create live keys or change billing.