What do the auth modes mean?

`none` — the skill needs no login. `session` — it runs off a stored browser session. `credentials` — it fills a vaulted credential at fill time. `interactive` — the host cannot be signed into by an agent and needs a human once, which is what connect_account is for. `ready` tells you whether that requirement is currently satisfied; `missing` names what is not.

Core tool

Read the run contract before you spend a credit

Every compiled skill with the contract attached: the params to pass, the secrets it fills, and whether this tenant is actually authorized on the host right now.

Get an API key MCP setup

list_catalog

What it is

The job: Let an agent plan: pick a skill it can actually run, with values it can actually supply.

The failure mode list_catalog exists to remove is the confident wrong call: an agent picks a skill by name, runs it, and discovers halfway through that the host needs a login it does not have. Catalog answers that up front. For each skill it returns the params the caller must supply, the secrets the skill fills from the vault, and an `auth` block — { mode: none | session | credentials | interactive, ready, missing[] } — that says whether this tenant is in a position to run it at all.

It is read-only and free, which makes it the correct first call in an agent loop. Filter to one site with `host` when you already know where you are going.

The catalog is also the honest inventory of the platform’s cheap path: if `auth.ready` is false and `mode` is interactive, the next call is connect_account, not a run that was always going to fail.

The call

Call it exactly like this.

Copied from the tool's registration and the route handler — not paraphrased.

MCPlist_catalog.mcp.jsonjson

// MCP tool call — server "twin-browser"
{
  "tool": "list_catalog",
  "arguments": {
    "host": "app.example.com"
  }
}

GET /api/v1/catalogrequest.shbash

curl -X GET "https://twin-browser.com/api/v1/catalog?host=app.example.com" \
  -H "Authorization: Bearer $TWIN_API_KEY"

GET /api/v1/catalog is a live route but is not described in the published OpenAPI document — the MCP tool is the documented surface for it. Treat the response shape below as the contract; it is read from the route handler.

Parameters accepted by list_catalog
Parameter	Type	What it does
host	string	Optional host or URL to scope the catalog, e.g. app.example.com. Omit for every skill in the tenant.

Returns

response.jsonjson

{
  "count": 3,
  "host": "app.example.com",
  "skills": [
    {
      "id": "…", "name": "acme-export", "goal": "…", "host": "app.example.com",
      "version": 2, "steps": 6,
      "params": [ … ], "secrets": [ … ], "vars": [ … ],
      "auth": { "mode": "credentials", "ready": true, "missing": [] }
    }
  ]
}

What it costs

Free

Read-only metadata. No reservation, no charge, no audit cost to you — the whole point is to be callable before every run.

See the full rate card

Which one

When a different tool is the right call.

The honest answer is often the neighbouring tool. These are the trades.

list_skills

list_skills is the same set of skills with none of the contract. Prefer catalog unless you specifically want a smaller payload.

list_skills

list_accounts

list_accounts answers “which logins do I hold?”; list_catalog answers “can I run THIS skill on THIS host?”. Catalog’s auth block is derived from the same credential state, scoped to one skill.

list_accounts

Questions

list_catalog, answered.

What do the auth modes mean?: `none` — the skill needs no login. `session` — it runs off a stored browser session. `credentials` — it fills a vaulted credential at fill time. `interactive` — the host cannot be signed into by an agent and needs a human once, which is what connect_account is for. `ready` tells you whether that requirement is currently satisfied; `missing` names what is not.

Keep going

The rest of the tool set.

run_skill

Run a known-good flow again, as cheaply as it can possibly be run.

list_skills

Answer “what do I already have?” before spending anything.

list_accounts

Answer “can I get into this site, and as whom?” before starting a run.

connect_account

Get logged into a site that an agent is not going to be allowed to log into.

The mechanism behind it:Skill library Credential vault Deterministic replay

Get an API key All tools