Access and explore my TinyCloud

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 data work. A delegation is a bearer artifact: approve only the exact requested capabilities and transfer it through a channel appropriate for account access.

MCP path

For Claude web/mobile and other remote clients, add https://mcp.tinycloud.xyz/mcp as a custom connector. Call tinycloud_connect, approve its one-time OpenKey link, and call it again before continuing with account discovery below. Hosted mode creates and maintains the delegate profile for you and requires @tinycloud/mcp 0.3.0 or newer on the hosted service. For a local MCP client, continue with the CLI bootstrap in this section. This 16-tool workflow requires @tinycloud/mcp 0.2.0 or newer and a deployed TinyCloud node running 1.6.0 or newer. The node release is deployed first, the stable MCP package is published second, and this guide is published last. 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:

npm install --global @tinycloud/cli @tinycloud/mcp
tc profile create agent --posture delegate-session --operator agent

A new delegated profile has a session key but no authenticated TinyCloud session. Bootstrap it with one exact account-registry request before starting MCP:

tc --profile agent --quiet --json auth request \
  --cap tinycloud.kv:account:spaces/:get,list \
  --emit request.json

Have the owner review and grant that exact artifact:

tc --profile owner --quiet --json auth grant request.json --yes > delegation.json

Then import it into the same delegated profile:

tc --profile agent --quiet --json auth import delegation.json

This one-time import establishes the delegated session. It does not grant app, prefix, key, write, SQL, or secret access beyond the exact account-space listing request. Configure MCP with the same explicit profile as described in TinyCloud MCP. The data surface is:

Tool	Purpose
`tinycloud_account_spaces_list`	List spaces in the canonical account registry
`tinycloud_account_applications_list`	List applications and their registered manifests
`tinycloud_kv_list`	List keys in one selected space, optionally under a prefix
`tinycloud_kv_get`	Read one selected key
`tinycloud_kv_head`	Read metadata and the current ETag for one selected key
`tinycloud_kv_put`	Create, conditionally replace, or explicitly upsert one selected key
`tinycloud_kv_delete`	Delete one selected key, optionally guarded by its ETag
`tinycloud_sql_schema_inspect`	Inspect one selected SQLite database
`tinycloud_sql_query`	Run one bounded `SELECT` against one selected SQLite database
`tinycloud_sql_execute`	Run one positional-parameterized `INSERT`, `UPDATE`, or `DELETE`

The remaining six tools manage the selected session and protected secret flow:

Tool	Purpose
`tinycloud_status`	Inspect safe local profile state
`tinycloud_auth_status`	Inspect authentication state
`tinycloud_auth_capabilities`	Inspect validated active capabilities
`tinycloud_auth_request`	Create or recover an exact permission request
`tinycloud_auth_import`	Validate and import a request-bound delegation
`tinycloud_secrets_get`	Read one specifically delegated secret

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. Account registry discovery is capped at 1,000 records, 1 MiB per record, and 4 MiB total serialized output. It fails closed instead of returning a partial registry. 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.

Store a file safely

TinyCloud KV values can hold arbitrary bytes. After selecting the target space and key, call tinycloud_kv_put with tagged content. For a Markdown file the tool input can be:

{
  "space": "<SPACE_URI>",
  "key": "agent-notes/sqlite-safety.md",
  "mode": "create",
  "content": {
    "encoding": "utf8",
    "value": "# SQLite safety notes\n\nUse bind parameters and bounded reads.\n"
  },
  "contentType": "text/markdown; charset=utf-8"
}

If that returns authority_required, complete the exact request flow below and retry the same input. create cannot overwrite an existing key. To update a known value safely, call tinycloud_kv_head, copy its strong quoted etag, and use mode: "replace" with that ETag. Use mode: "upsert" only when overwriting without a concurrency check is intentional. For binary files, base64-encode the bytes and use { "encoding": "base64", "value": "..." }. KV reads and writes are capped at 1 MiB. tinycloud_kv_get defaults to base64 and also supports explicit text and json representations. It returns the representation tag, byte length, ETag, and available content metadata. Delete only a selected key. Passing the ETag from tinycloud_kv_head to tinycloud_kv_delete prevents deleting a value that changed after inspection. If a conditional mutation reports a retryable database serialization conflict, re-read the key state, which may still be absent. If it exists, compare its current ETag before deciding whether to retry. Deletion removes the key from reads and listings immediately; retained content-addressed blob bytes, including historical versions, continue to count toward storage quota unless a future garbage collector safely reclaims them. Generic KV tools cannot access the protected account or secrets spaces.

Inspect SQLite

Call tinycloud_sql_schema_inspect with an exact space and database first. Then call tinycloud_sql_query with the same target, exactly one SQLite SELECT, and optional bind params. These MCP tools do not execute writes, DDL, pragmas, attachments, or multiple statements. Queries default to 100 rows and 1 MiB and allow explicit limits up to 1,000 rows and 4 MiB. Oversized results fail instead of being silently truncated. SQLite BLOB parameters use { "type": "blob", "base64": "..." }; BLOB results use the same tag and include byteLength. Each SQL read tool requests read capability for the exact database, not the entire space.

Mutate SQLite data

tinycloud_sql_execute is destructive and non-idempotent. It accepts exactly one INSERT, UPDATE, or DELETE with at least one positional ? placeholder and one params value per placeholder. The input must explicitly include acknowledgeDatabaseWideAuthority: true:

{
  "space": "<SPACE_URI>",
  "database": "notes",
  "sql": "INSERT INTO notes (body, status) VALUES (?, ?)",
  "params": ["Review delegation boundaries", "draft"],
  "acknowledgeDatabaseWideAuthority": true
}

The tool rejects literal-only mutations, CTEs, DDL, pragmas, attachments, and multiple statements. Its result reports the statement type, changed-row count, and last inserted row ID when available.

The requested tinycloud.sql/write capability is broader than this tool. Approving it grants full read, write, and schema-mutation authority over the exact database, including when the delegation is used outside MCP. It is not scoped to a table, row, SQL statement, or the three mutation types enforced by tinycloud_sql_execute. Approve only when database-wide authority is intended.

Execution failures are never marked automatically retryable. Because the tool is non-idempotent, inspect database state before deciding whether another write is safe.

Two-agent approval

Use separate delegate and owner agents when a data tool returns authority_required.

The delegate agent calls the data tool and saves the returned tinycloud.auth.request object exactly as request.json. Do not edit its request ID, audience, host, or capabilities.
The owner agent reviews the artifact. It must contain only the exact account-registry, KV key or prefix, or SQLite database capabilities expected for this step. A write or delete request must match the user’s stated action. For tinycloud.sql/write, the owner must separately accept that the actual capability is database-wide rather than table- or row-scoped.
The owner agent grants that exact request with an explicit owner profile:

tc --profile owner --quiet --json auth grant request.json --yes > delegation.json

The delegate agent passes the complete delegation object to tinycloud_auth_import.
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 KV or SQLite call needs a capability that was not in the first request. Do not replace an exact 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:

tc --profile owner --quiet --json account spaces list --live
tc --profile owner --quiet --json account apps list --live
tc --profile owner --quiet --json account spaces info <SPACE_ID>
tc --profile owner --quiet --json account apps info <APP_ID>

--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:

tc --profile owner --quiet --json kv list --space <SPACE_URI> --prefix <PREFIX>
tc --profile owner --quiet --json kv get <KEY> --space <SPACE_URI>

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 write or delete was not explicitly requested, or its exact target is unclear
a SQL read request is not one bounded read-only SELECT
a SQL mutation lacks the explicit database-wide-authority acknowledgment
the owner does not accept database-wide SQL write and schema authority
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.

​MCP path

​Store a file safely

​Inspect SQLite

​Mutate SQLite data

​Two-agent approval

​Owner CLI inspection

​Stop conditions

MCP path

Store a file safely

Inspect SQLite

Mutate SQLite data

Two-agent approval

Owner CLI inspection

Stop conditions