Skip to main content
Use this workflow when an agent needs to discover what is in a user’s TinyCloud without receiving the user’s owner identity. The delegated path uses MCP. The CLI section is an owner-side inspection fallback, not an equivalent delegate workflow.
Keep the agent on a delegate-session profile. Do not start MCP with an owner profile or --allow-owner-profile for exploration. A delegation is a bearer artifact: approve only the requested read capabilities and transfer it through a channel appropriate for account access.

​
MCP path

Install the CLI and MCP packages with Node.js 20 or newer, then create a delegated agent profile once if one does not already exist:
A new delegated profile has a session key but no authenticated TinyCloud session. Bootstrap it with one exact account-registry request before starting MCP:
Have the owner review and grant that exact artifact:
Then import it into the same delegated profile:
This one-time import establishes the delegated session. It does not grant app, prefix, key, write, or secret access beyond the exact account-space listing request. Configure MCP with the same explicit profile as described in TinyCloud MCP. The exploration surface is: Call tinycloud_account_spaces_list first. Compare its space IDs with tinycloud_account_applications_list, then choose a space and call tinycloud_kv_list. Read individual keys with tinycloud_kv_get only after their names and app context are known. Do not treat an application name as permission to read every key in its space. Use its manifest and any linked knowledge bundle to identify relevant prefixes and data shapes. See Agent-readable Apps.

​
Two-agent approval

Use separate delegate and owner agents when the exploration tool returns authority_required.
  1. The delegate agent calls the read tool and saves the returned tinycloud.auth.request object exactly as request.json. Do not edit its request ID, audience, host, or capabilities.
  2. The owner agent reviews the artifact. It must contain only the account registry or selected KV read capabilities expected for this step.
  3. The owner agent grants that exact request with an explicit owner profile:
  1. The delegate agent passes the complete delegation object to tinycloud_auth_import.
  2. The delegate agent retries the same exploration tool. Imports persist in the selected profile, so approval and retry may happen in different MCP process sessions.
Repeat the exchange if a later tinycloud_kv_list or tinycloud_kv_get call needs a narrower capability that was not in the first request. Do not replace that request with a broad space-wide grant.

​
Owner CLI inspection

When MCP is unavailable, the owner can inspect the same registries locally and return a read-only summary to the agent. Use an explicit owner profile, machine-readable output, and canonical live account reads:
--live matters for read-only discovery. The default indexed spaces path may refresh and register accessible spaces when its index is empty. After selecting a space, list keys and read only the chosen key:
Current tc account commands derive the account registry from the active profile. Do not run these commands with a delegate profile and assume they target the owner’s account. Use the MCP tools and their canonical per-operation requests for delegated exploration.

​
Stop conditions

Stop and return the structured result instead of widening authority when:
  • the owner rejects or changes the request
  • a space or app is absent from the canonical account registry
  • the app manifest does not explain a prefix or value shape
  • a command would write, register, sync, delete, or revoke data
  • the next step needs a secret value that the user did not request
Secret tools have an additional transcript boundary: the MCP server keeps secret values out of text results and TinyCloud logs, but the MCP client may retain structured results. See TinyCloud MCP before reading secrets.