Agents over plain HTTPS

The routes

On the platform host, https://mcp.substrio.com, where an app tool names its app. The same routes run on an app's own host, where every tool runs at that app and names none.

The credential is Authorization: Bearer <key>: an agent session, an account key or the system key, as on /mcp. With no credential, only POST /v1/_agent/tools/substrio_connect {"code": "..."} runs; it is the exchange above by its tool name.

An app tool names its app with "app": "<slug>" in the body. The call runs at that app and answers the same way. substrio_route_call answers 200 with the route's own answer inside: {"status", "headers", "body"}.

Refusals

Example

# 1. Redeem the code your owner gave you.
curl -X POST https://mcp.substrio.com/v1/_agent/exchange \
  -H 'Content-Type: application/json' -d '{"code":"substrio_ae_..."}'
# {"id":"...","kind":"bearer",...,"key":"substrio_ab_...","next":"Keep key, shown only once. ..."}

# 2. Make an app, then commit a function with one route.
curl -X POST https://mcp.substrio.com/v1/_agent/tools/substrio_account_app_create \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"id": 7, "slug": "my-app"}'
curl -X POST https://mcp.substrio.com/v1/_agent/tools/substrio_version_commit \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"app":"my-app","message":"hello","units":[
        {"path":"functions/hello.js","text":"module.exports = async () => new Response(\"hi\");"},
        {"path":"functions/hello.json","text":"{\"routes\":[\"GET /hello\"]}"}]}'
# {"number":1,...,"next":[{"tool":"substrio_sandbox_create","why":"..."},...]}

# 3. Run it in a sandbox, check it, make it live.
curl -X POST .../v1/_agent/tools/substrio_sandbox_create -d '{"app":"my-app","name":"dev"}' ...
curl -X POST .../v1/_agent/tools/substrio_live_set -d '{"app":"my-app","version":1,"sandbox":"dev"}' ...
curl -X POST .../v1/_agent/tools/substrio_route_call -d '{"app":"my-app","method":"GET","path":"/hello","sandbox":"dev"}' ...
curl -X POST .../v1/_agent/tools/substrio_live_set -d '{"app":"my-app","version":1}' ...
curl https://my-app.substrio.com/hello

The same loop over MCP is in agents.md; the tools themselves are in MCP.

Agents that can only open links

Some agents can only open a link: a GET with no header of their own and no body (ChatGPT on the web is one). They reach every tool too. The session's secret is in the link's path, so the link itself is the credential.

1. Your owner makes a connect code on the console's Agents page.
2. Open https://mcp.substrio.com/v1/_agent/go/<code>. It redeems the code for a session of kind link, as the exchange does, and answers the session's home. Opened again within agent_enroll_ttl_seconds (10 minutes) it answers the same home; after that it is AGENT_CODE_INVALID. A code opened as a link is spent: no other exchange redeems it.
3. Every URL the answers give starts with the link, https://mcp.substrio.com/v1/_agent/link/<link>. Open only those.

Every answer, a refusal too, adds:

• owner: your owner's line (account, plan, apps, storage, the limits it meets), as an MCP result ends with it.
• tell_your_owner: before each call, tell your owner in one line what you are about to do; after it, what happened.
• next: on a success, the tools that come next, each with its url.
• home: the link's home, where every tool is listed.

A body that is not a JSON object comes as result, a string. Every link answer is sent with Cache-Control: no-store, X-Robots-Tag: noindex, nofollow and Referrer-Policy: no-referrer.

A call your owner must approve answers APPROVAL_REQUIRED (403) with approve_url, the console page where they approve it. Ask your owner to approve it there, then open the same link again: it runs once.

A link lives as a bearer session does (agent_bearer_max_seconds, idle agent_bearer_idle_seconds) and is listed, and revoked, with the account's agent sessions, as kind link. An ended link answers CREDENTIAL_REQUIRED (401): ask your owner for a new code.

The request's head (its line and headers) is at most head_max_bytes (4096). A link past it is refused 431 before it reaches a tool. Write a larger file one unit a call (substrio_version_commit), or edit it in parts (substrio_source_edit).

# The code your owner gave you, opened:
GET https://mcp.substrio.com/v1/_agent/go/substrio_ae_...
# {"account":{"id":7,"name":"Ada"},"approvals_waiting":[],
#  "tools":[{"name":"substrio_account_app_create","title":"...",
#            "url":"https://mcp.substrio.com/v1/_agent/link/substrio_al_.../substrio_account_app_create",
#            "about":".../substrio_account_app_create/about"},...],
#  "head_max_bytes":4096,"next":[...],"owner":{"type":"text","text":"Account 7, Free plan: ..."},
#  "tell_your_owner":"Before each call, ...","home":"https://mcp.substrio.com/v1/_agent/link/substrio_al_..."}

# Make an app, commit a function, run it, make it live:
GET .../substrio_account_app_create?id=7&slug=my-app
GET .../substrio_version_commit?app=my-app&message=hello&args=%7B%22units%22%3A%5B...%5D%7D
GET .../substrio_sandbox_create?app=my-app&name=dev
GET .../substrio_live_set?app=my-app&version=1&sandbox=dev
GET .../substrio_route_call?app=my-app&method=GET&path=%2Fhello&sandbox=dev
GET .../substrio_live_set?app=my-app&version=1