# substrio, for agents

Your person sent you here so you can build for them on substrio. substrio is an app platform: their account holds their apps, and each app is complete with its own host, data, functions, files, users and site. With their agent key you can do everything they can: make apps, change any app's settings, write its functions and code, upload its files, and ship it.

## 1. Get the key

Ask your person for their **agent key**. It starts with `substrio_live_`.

If they have none, send them to **https://substrio.com/keys**: they sign in (or create their sign-in), click "Make an agent key", and paste you the key. It takes a minute. This is the way to use first.

If you can make HTTPS requests and your person can read their email inbox right now, you can get the key for them instead with a mailed code. You ask for two things only, their email and then the code:

1. `POST https://mcp.substrio.com/v1/_auth/email/code_request` with `{"email": "..."}` and the header `X-Substrio-Tenant: substrio`. A six-digit code is emailed to them.
2. Ask them for the code. `POST https://mcp.substrio.com/v1/_auth/email/code_verify` with `{"email": "...", "code": "..."}` and the same header. Keep the reply's `token`.
3. `GET https://mcp.substrio.com/v1/_accounts` with `Authorization: Bearer <token>`. Their account is the one with `"personal": true`.
4. `POST https://mcp.substrio.com/v1/_accounts/{id}/keys` with `{"name": "<your name>"}` and the same token. The reply's `key` is the agent key.

The key opens their whole account. Send it only to `mcp.substrio.com` and to the hosts of their apps, as `Authorization: Bearer <key>`. Never put it in code you ship, and never show it again once you have it.

## 2. Connect

**MCP** (Claude Code, Cursor, VS Code, Windsurf, Zed, any client that sends headers): the server is `https://mcp.substrio.com/mcp` with the header `Authorization: Bearer <key>`.

- Claude Code: `claude mcp add --transport http substrio https://mcp.substrio.com/mcp --header "Authorization: Bearer <key>"`
- Cursor (`.cursor/mcp.json`), VS Code and other JSON configs:

```json
{
  "mcpServers": {
    "substrio": {
      "type": "http",
      "url": "https://mcp.substrio.com/mcp",
      "headers": { "Authorization": "Bearer <key>" }
    }
  }
}
```

**ChatGPT and other connectors that only sign in** (no headers): add `https://mcp.substrio.com/mcp` as a connector. Your person signs in with their email and a code and approves every app. No key is needed.

**HTTPS** (any agent with a web, fetch or code tool): call `https://mcp.substrio.com/v1/...` with JSON bodies and the same `Authorization: Bearer <key>`. The reference is `https://mcp.substrio.com/v1/_openapi` (large: read only the paths you need).

## 3. Build

Start with `substrio_start {"app": "<slug>"}` for an app, and `substrio_tools {"app": "<slug>", "area": "<area>"}` to see an area's tools. Every app tool names its app with `"app": "<slug>"`.

- **The account**: apps (create, list, delete), agent keys, members.
- **Each app**: functions and code, data and schema, files, secrets, schedules, domains, versions (push to a sandbox, then make it live), logs.

A new app is `substrio_account_app_create` with `{"slug": "my-app"}`; the slug names its host, `https://my-app.substrio.com`. Over HTTPS the same operations are the `/v1/...` paths of the reference; an app's own calls name it with the header `X-Substrio-Tenant: <slug>`.

A call that cannot be undone (deleting an app, attaching a domain) asks your person to approve it first. Tell them what it does before you make it.

## Working with your person

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