# TinyCloud Docs TinyCloud docs are organized around reader intent and Diataxis. Start at `/` to choose a path, then move into concepts or reference when you need the system model or exact action names. For release-sensitive MCP details, use the current Markdown pages linked below. The Mintlify-generated `/llms-full.txt` aggregate is cached separately and can lag a documentation deployment. ## Agent access quickstart TinyCloud MCP supports two transports. Claude web, iOS, Android and other remote clients connect to `https://mcp.tinycloud.xyz/mcp` using OpenKey OAuth. Hosted mode exposes 20 tools: it adds `tinycloud_connect` and four apps tools to the 17-tool local surface, omitting local-only `tinycloud_auth_import` and `tinycloud_secrets_status`. Local clients install `@tinycloud/mcp` alongside `@tinycloud/cli` and run its stdio server; MCP is not a `tc` subcommand. For hosted access, add `https://mcp.tinycloud.xyz/mcp` as a custom connector, complete the OpenKey sign-in, and call `tinycloud_connect`. If it returns an `approvalUrl`, open that URL, approve the account-registry delegation, then call `tinycloud_connect` again. Continue only after it returns `connected: true`. Later `authority_required` results carry an exact approval URL; approve the request and retry the original tool unchanged. Local stdio requires Node.js 20 or newer and a deployed TinyCloud node running 1.6.0 or newer. Hosted apps do not require local CLI or skill installation. For personal records, ask naturally: “Log my weight: 80.5 kg today.” Approve connect and records access in OpenKey. `tinycloud_apps_context` returns rules, catalog, local time, timezone and fast-copy state; `tinycloud_apps_read` lists prefixes and reads records with ETags; `tinycloud_apps_write` runs 1–10 ordered create, conditional edit, move or delete operations; `tinycloud_apps_query` refreshes the optional fast copy and queries selected kinds. All four are hosted-only. Records use one get/list/put/delete prefix grant under `xyz.tinycloud.agent-data/` in `default`; generic KV exact scopes are unchanged. Ask for the owner's city once and store the IANA timezone. Fresh ETags protect edits; `CHANGED` means re-read, not overwrite. Inspect every write outcome and completed move step, and report partial success rather than replaying a batch. In Claude Settings → Connectors → TinyCloud, `tinycloud_apps_write` can be set to Always allow; this does not replace OpenKey approval. Offer “a fast, searchable copy of your records” for larger questions, after answering from KV when no copy is approved. It is optional and separately approved; KV remains the source of truth. Developer detail: the exact SQL database is `xyz.tinycloud.agent-data.index`, with read/write/schema authority. `COPY_PARTIAL` is an ok result listing remaining kinds; the next query resumes. A nonretryable `NODE_ERROR` with `error.details.reason: "copy_unavailable"` requires the node team; answer from KV rather than retrying the copy. Production compose sets `TC_MCP_DELEGATION_EXPIRY=30d` and `TC_MCP_APPROVAL_TTL_SECONDS=900`. Standalone defaults remain `1h` and 300 seconds. `TC_HOST` defaults to `https://tee.node.tinycloud.xyz`. Missing/expired sessions return a fresh connect link in `error.details`; missing/expired grants return an `authority_required` link. Renew through owner approval; stop if declined. Hosted text carries readable canonical JSON alongside structuredContent, except successful secret values remain structured-only. Read-only results over 100,000 characters fail with narrowing guidance; write results are never truncated by this cap. Logs contain only tool, outcome code, duration and successful replayed-grant count, never keys, values, catalog text, SQL or params. The MCP data surface can discover account spaces and applications; list, read, inspect, create, replace, upsert, and delete selected KV values; inspect one SQLite schema; run one bounded read-only SQLite `SELECT`; run one constrained SQLite `INSERT`, `UPDATE`, or `DELETE`; and read a delegated secret. Generic KV access blocks the protected `account` and `secrets` spaces. Treat file-like values according to the owning app's manifest and schema. For local stdio, install the packages and create a delegated agent profile: ```sh npm install --global @tinycloud/cli @tinycloud/mcp tc profile create agent --posture delegate-session --operator agent ``` A fresh delegate profile must bootstrap once. The delegate emits one exact account-registry request: ```sh tc --profile agent --quiet --json auth request \ --cap tinycloud.kv:account:spaces/:get,list \ --emit request.json ``` An authenticated owner reviews and grants that exact artifact, then the delegate imports the returned delegation: ```sh tc --profile owner --quiet --json auth grant request.json --yes > delegation.json tc --profile agent --quiet --json auth import delegation.json ``` Configure the MCP client to start the server with that explicit profile: ```json { "mcpServers": { "tinycloud": { "command": "tinycloud-mcp", "args": ["--profile", "agent"] } } } ``` Use these exact data tools after selecting the delegated profile: - `tinycloud_account_spaces_list` - list the canonical account space registry - `tinycloud_account_applications_list` - list registered apps and manifests - `tinycloud_kv_list` - list keys in one selected space or prefix - `tinycloud_kv_get` - read one selected KV key - `tinycloud_kv_head` - read metadata and the ETag for one selected KV key - `tinycloud_kv_put` - create, ETag-replace, or explicitly upsert one selected KV key - `tinycloud_kv_delete` - delete one selected KV key, optionally guarded by its ETag - `tinycloud_sql_schema_inspect` - inspect one exact SQLite database - `tinycloud_sql_query` - run one bounded `SELECT` against one exact SQLite database - `tinycloud_sql_execute` - run one positional-parameterized `INSERT`, `UPDATE`, or `DELETE` KV values are capped at 1 MiB. Base64 is the default lossless representation; UTF-8 and JSON are explicit tagged alternatives. Use `create` to prevent overwrite, or read an ETag with `tinycloud_kv_head` and pass it to `replace` or delete for optimistic concurrency. On a retryable database serialization conflict, re-read key state, which may still be absent, and compare the current ETag when present before retrying. Deleted keys disappear from reads and lists immediately, while retained content-addressed blob bytes, including historical versions, count toward quota unless a future garbage collector safely reclaims them. Account discovery is capped at 1,000 records, 1 MiB per record, and 4 MiB total output and fails rather than returning a partial registry. SQL query defaults are 100 rows and 1 MiB; hard maxima are 1,000 rows and 4 MiB. Oversized SQL results fail without silent truncation, and SQL BLOBs use tagged base64 values. `tinycloud_sql_execute` is destructive and non-idempotent. It requires at least one positional `?`, one `params` value per placeholder, and `acknowledgeDatabaseWideAuthority: true`. The tool accepts only one `INSERT`, `UPDATE`, or `DELETE`, but its requested `tinycloud.sql/write` capability grants full read, write, and schema-mutation authority over the exact database outside the narrower tool. This authority is not table- or row-scoped. Execution failures are not automatically retryable; inspect database state before considering another non-idempotent write. In local stdio, when a tool returns `authority_required`, preserve its returned `tinycloud.auth.request` exactly. The owner grants that artifact without widening it, the delegate imports the full delegation with `tinycloud_auth_import`, and the agent retries the original tool. Hosted mode uses the approval URL and callback instead; it does not expose the import tool. Complete readable pages: - MCP reference (Markdown): https://docs.tinycloud.xyz/cli/mcp.md - Delegated exploration guide (Markdown): https://docs.tinycloud.xyz/guides/access-and-explore-my-tinycloud.md - Hosted MCP operations guide (Markdown): https://docs.tinycloud.xyz/hosting/mcp.md ## Entry points - `/` - Homepage and reader-journey selector - `https://mcp.tinycloud.xyz/mcp` - Hosted Streamable HTTP MCP connector for remote clients - `https://docs.tinycloud.xyz/cli/mcp` - Hosted and local MCP setup and tool reference - `https://docs.tinycloud.xyz/guides/access-and-explore-my-tinycloud` - MCP-first delegated discovery, safe KV CRUD, and SQLite operations - `/start/browser-app` - Web SDK path from sign-in to first KV write - `/start/backend-service` - Node SDK path and sign-in mode decision - `/start/protocol` - Capability, manifest, and delegation vocabulary - `/start/operator` - CLI, hosting, OpenKey, and troubleshooting path ## Build and understand - `/quickstart/web-sdk` - `/quickstart/node-sdk` - `/guides/agent-skills` - Install the `tc-cli` agent skill and app skill packs - `/guides/authentication` - `/guides/authentication/web` - `/guides/authentication/node` - `/guides/browser-e2e-testing` - Automated OpenKey + TinyCloud E2E testing for agents and CI - `/guides/spaces` - `/guides/spaces/provisioning` - `/guides/kv-storage` - `/guides/local-replicas` - Beta guide to scoped, read-only KV replicas for offline reads - `/guides/kv/basic-operations` - `/guides/delegations` - `/guides/sharing` - SDK `tc1:` bearer tokens - `/guides/share-viewer` - What Share recipients see; receive addressed shares with the Web SDK - `/guides/data-vault` - `/guides/write-hooks` - `/guides/sql-schema-and-migrations` - `/guides/tinycloud-vfs` - `/guides/agent-readable-apps` - `/concepts/system-model` - `/concepts/security-and-trust` - `/concepts/did-formats` - `/concepts/capabilities` - `/concepts/app-manifests` - `/concepts/data-vault` - `/reference/glossary` - `/reference/protocol/capabilities` - `/reference/protocol/app-manifests` - `/reference/protocol/delegations` - `/reference/sdk/index` - `/reference/sdk/web` - `/reference/sdk/node` ## Operate - `/cli/overview` - `https://docs.tinycloud.xyz/cli/mcp` - Hosted Streamable HTTP MCP with 20 tools and local stdio MCP with 17 tools - `/cli/account` - Read-only live account space and application discovery commands - `/cli/authentication` - `/cli/storage` - `/cli/sql` - `/cli/duckdb` - `/cli/spaces` - `/cli/secrets` - `/cli/delegations` - `/cli/share` - Publish bearer and addressed Share links, notify, and revoke - `/cli/auth-artifacts` - `/cli/profiles` - `/cli/status` - `/cli/manifest` - `/cli/diagnostics` - `/hosting/overview` - `/hosting/mcp` - Deploy the OAuth-protected hosted MCP resource - `/hosting/configuration` - `/hosting/docker` - `/hosting/databases` - `/hosting/storage` - `/hosting/monitoring` - `/openkey/index` - `/openkey/local-development` - `/openkey/quickstart` - `/openkey/widget` - `/openkey/oauth` - `/openkey/tinycloud-integration` - `/troubleshooting` ## Source and validation - Preview locally with `mint dev`. - Keep `reference/protocol/capabilities.mdx` synced with `npm run sync-capabilities`. - Verify the generated registry with `npm run check-capabilities`.