# substrio, for agents

**Have a code?** Open `https://mcp.substrio.com/v1/_agent/go/<code>`. If you can only open links (no headers, no body), that link is all you need. Its answer lists every tool as a link, and every answer tells you the next one ([agents that can only open links](https://substrio.com/docs/agent-http/#agents-that-can-only-open-links)).

Your owner sent you here so you can build for them on substrio. substrio is an app platform. Their account holds their apps, and each app comes with a host, data, functions, files, users, and a site.

## 1. Sign in

If you can run commands on your owner's machine, sign them in with the CLI:

```
npx @substrio/cli login --email owner@example.com
```

The CLI prints a short match code and opens a sign-in page in their browser. Tell your owner the match code and ask them to check that the page shows the same one. They pass the bot check and type the code from their email. Their browser is signed in to the dashboard, and the CLI saves your session. A new address gets its account and a free plan at the same time.

The session refreshes itself. You never handle a key, and your owner can end the session from the dashboard at any time.

**If the browser does not finish.** Your owner may sign in on another device, or the page may not reach the CLI. After 100 seconds the CLI exits with code 75. Ask your owner for the six-digit code from their email, then run:

```
npx @substrio/cli login --code <code>
```

The same code works for you even after your owner used it in the browser. To give the browser another 100 seconds instead, run `npx @substrio/cli login --wait`.

**Open their dashboard.** Run `npx @substrio/cli open --dashboard`. It opens your owner's dashboard in this machine's browser, already signed in.

**An agent key.** If you cannot run the CLI, ask your owner for an agent key (it starts with `substrio_live_`). If they have none, send them to **https://substrio.com/keys**. They sign in, click "Create Agent Key", and paste you the key. Send it as `Authorization: Bearer <key>` on every request.

**A connect code.** If your owner gave you a code that starts with `substrio_ae_`, redeem it once with `npx @substrio/cli connect <code>`, or over HTTPS:

```
curl -X POST https://mcp.substrio.com/v1/_agent/exchange -H 'Content-Type: application/json' -d '{"code":"substrio_ae_..."}'
```

Keep the reply's `key`, which is shown once. Its `next` line says how long it lasts. When it ends, ask your owner for a new code.

Send a key only to `mcp.substrio.com` and to the hosts of their apps. Never put it in code you ship, and never show it again.

## 2. Build

In a project folder, the CLI runs the whole loop:

```
npx @substrio/cli init --tenant my-app --yes
npx @substrio/cli dev
npx @substrio/cli push -m "first version"
npx @substrio/cli promote
```

- `init` writes `substrio.toml`, a `functions/` folder, and a sample function. The app's host is `https://my-app.substrio.com`.
- `dev` runs the app on its dev sandbox with hot reload. Each save runs there as a new version, the sandbox's logs stream to the terminal, and the live app does not change.
- `push` uploads a new version and runs it in the dev sandbox. It prints the sandbox's address, so you can check it there.
- `promote` makes that version live. The data is backed up first, and `rollback` undoes it.
- `op <name>` calls any operation of the platform by name, with its input as JSON. `npx @substrio/cli op --help` lists them.

A call that cannot be undone, such as deleting an app or attaching a domain, asks your owner to approve it first. Tell them what it does before you make it. The whole guide is at https://mcp.substrio.com/llms.txt.

## 3. Connect over MCP

**MCP** works in Claude Code, Cursor, and any client that sends headers. Connect to `https://mcp.substrio.com/mcp` with the header `Authorization: Bearer <key>`. For example, `claude mcp add --transport http substrio https://mcp.substrio.com/mcp --header "Authorization: Bearer <key>"`.

**ChatGPT and other connectors that only sign in** add `https://mcp.substrio.com/mcp` as a connector. Your owner signs in and approves. No key or code is needed.

**HTTPS** works for any agent that can make a request. Every tool is one call.

- `GET https://mcp.substrio.com/v1/_agent/tools` lists the everyday tools your key reaches (`name`, `title`). `?area=all` lists every one.
- `GET https://mcp.substrio.com/v1/_agent/tools/<name>` describes one tool, with its `inputSchema`.
- `POST https://mcp.substrio.com/v1/_agent/tools/<name>` runs it, with its arguments as the body. The answer is the operation's status and body. It carries `next` when there is a next step, and `fix` on a refusal that has one.

## Working with your owner

- Ask only for what you need: their email, then the code if the CLI asks for it, or a key.
- Tell them what you are about to build, in their words, before you build it.
- When an app is live, show them its address.