TinyCloud MCP

The TinyCloud MCP server exposes 20 hosted tools or 17 local stdio tools to Model Context Protocol clients. Use the hosted Streamable HTTP endpoint from web and mobile clients, or run local stdio when data and delegate keys must remain on your machine. Both paths use scoped, revocable authority.

Connect Claude web, iOS or Android

Add a custom connector in Claude and use this URL:

https://mcp.tinycloud.xyz/mcp

Claude discovers OpenKey OAuth from the endpoint, registers its OAuth client, and asks you to sign in. After the connector is enabled:

Ask Claude to call tinycloud_connect.
Open the returned approvalUrl and approve the account-registry delegation in OpenKey.
Ask Claude to call tinycloud_connect again. It now returns connected: true.
Ask Claude to list your spaces, then perform the KV or SQLite operation you want. When a tool returns authority_required, open its approval.url and retry the same tool unchanged.

Hosted mode adds tinycloud_connect and four personal-record tools to the local surface, and omits the local-only tinycloud_auth_import and tinycloud_secrets_status. The service stores a distinct delegated session key for each OpenKey OAuth subject and accepts only delegations from an owner DID carried by that subject’s resource-bound access token. It never receives an owner private key.

Keep personal records naturally

Ask “Log my weight: 80.5 kg today”, “Mark my passport todo done”, or “How much did I run last month?” Claude can keep and read the same records as coding agents using tc-apps, without a local CLI or skill installation. At first use, approve connect and then personal-record access in OpenKey. Records use one grant for get, list, put and delete under xyz.tinycloud.agent-data/ in your default space, not a separate approval for every key. Claude asks for your city once to store an IANA timezone; it must not infer your local date from the hosted server’s clock. In Settings → Connectors → TinyCloud, you can set tinycloud_apps_write to Always allow to avoid per-call tool confirmations. This does not bypass OpenKey permission approval.

Hosted-only tool	Purpose
`tinycloud_apps_context`	Read the rules, catalog, local time, timezone and fast-copy state; optionally set the timezone
`tinycloud_apps_read`	List prefixes and read up to 100 records with their ETags
`tinycloud_apps_write`	Run 1–10 ordered create, conditional edit, move or delete operations
`tinycloud_apps_query`	Refresh the optional fast copy and answer a bounded question over selected kinds

For edits, read fresh and pass the returned ETag. A put without an ETag creates only; a stale ETag returns CHANGED, not an overwrite. A move requires the source ETag; a delete can also be guarded by one. Inspect each operation’s outcome and a move’s completed steps (written, deleted): an ok envelope does not mean every operation succeeded. Report partial outcomes rather than blindly replaying the batch. TIMEZONE_REQUIRED means the owner’s timezone must be set before the write. For questions over many records, Claude can first answer from the records and offer a fast, searchable copy of your records. This is optional and needs its own approval. KV records remain the source of truth. Developer reference: the copy is the exact SQL database xyz.tinycloud.agent-data.index, with read, write and schema authority; query refreshes derived data, not KV records. COPY_PARTIAL is a successful result with the kinds still to rebuild; the next query resumes them. A nonretryable NODE_ERROR with error.details.reason: "copy_unavailable" needs the node team’s resolution. Answer from KV instead; retrying the copy or changing its name is not a fix. Production requests 30-day grants and uses 15-minute approval links. A missing or expired session returns a fresh connect link in error.details; a missing or expired grant returns an authority_required approval link. Open the new link and retry after approval. If the owner declines, stop rather than asking again in that conversation.

The hosted service can observe plaintext operation inputs and results while it executes them, including delegated secrets. Use local stdio instead when the service operator must not be in that trust boundary.

Requirements

Node.js 20 or newer
The TinyCloud CLI and a delegated profile for local stdio
A hosted deployment with the apps tools for personal records; local stdio does not expose them
A TinyCloud node running 1.6.0 or newer
Local stdio requires structured tool results; hosted clients can also read canonical JSON in text results

Configure local stdio

Install both packages with Node.js 20 or newer:

npm install --global @tinycloud/cli @tinycloud/mcp

Before starting MCP with a newly created delegate-session profile, complete the one-time exact request, owner grant, and CLI import in Access and explore my TinyCloud. Then add the local stdio server to your MCP client:

{
  "mcpServers": {
    "tinycloud": {
      "command": "tinycloud-mcp",
      "args": ["--profile", "agent"]
    }
  }
}

The server captures the selected profile at startup. Restart it to select a different profile. Delegation imports persist, so retry can happen in the same process or a later one.

Available tools

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 (local only)
`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, conditionally replace, or explicitly upsert one selected KV key
`tinycloud_kv_delete`	Delete one selected KV key, optionally only when its ETag matches
`tinycloud_sql_schema_inspect`	Inspect tables, views, indexes, and triggers in one SQLite database
`tinycloud_sql_query`	Run one bounded read-only query against one SQLite database
`tinycloud_sql_execute`	Run one positional-parameterized `INSERT`, `UPDATE`, or `DELETE`
`tinycloud_secrets_get`	Read and decrypt one delegated secret
`tinycloud_secrets_status`	Inspect delegated secret readiness without reading values (local only)

These tools use the same versioned operation contracts as the CLI projections. Results use one of four statuses: ok, authority_required, setup_required, or error. Generic data operations plan authority for the exact space and key, prefix, or database in their input. The hosted apps tools use the single records-prefix grant described above instead. When authority is missing, the tool returns authority_required with a tinycloud.auth.request; it does not widen the request or silently fall back to owner authority. Generic KV tools reject the TinyCloud account and secrets spaces. Use the dedicated account and secret tools for those protected spaces. For the MCP-first account and data discovery sequence, including a separate owner agent that grants exact read requests, see Access and explore my TinyCloud. 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. Hosted text results include readable canonical JSON as well as structuredContent, except that successful secret values remain structured-only. Read-only results over 100,000 characters return a nonretryable size error with narrowing guidance. This cap never truncates write results or conceals completed writes. Tool-call logs contain only tool name, outcome code, duration and the number of successfully replayed grants—not keys, values, catalog text, SQL or parameters.

KV data safety

tinycloud_kv_list returns at most 100 keys by default, accepts a limit from 1 through 1,000, and reports whether the result was truncated. KV reads and writes are limited to 1 MiB per value. tinycloud_kv_get returns the byte length, metadata, and a tagged representation. Base64 is the default and preserves arbitrary files exactly; request text or json only when the bytes use that representation. A decoded GET can carry a weak representation ETag; use tinycloud_kv_head when a strong validator is needed for a conditional mutation. tinycloud_kv_put accepts one of these tagged content objects:

{ "encoding": "utf8", "value": "# Field notes\n" }
{ "encoding": "json", "value": { "status": "draft" } }
{ "encoding": "base64", "value": "AAECAw==" }

Choose the write mode deliberately:

create succeeds only when the key does not exist.
replace requires the current strong ETag from tinycloud_kv_head and fails if the value changed.
upsert writes without a precondition and can overwrite an existing value.

For deletion, pass the current ETag to tinycloud_kv_delete when concurrent changes must be preserved. A failed create, replace, or guarded delete returns a precondition error instead of overwriting or deleting newer data. 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 immediately removes the key from reads and listings, but retained content-addressed blob bytes, including historical versions, continue to count toward storage quota unless a future garbage collector safely reclaims them.

SQLite reads

tinycloud_sql_schema_inspect uses a fixed query to list user tables, views, indexes, and triggers. tinycloud_sql_query accepts exactly one SQLite SELECT, optional bind parameters, and no write, DDL, attachment, pragma, or multi-statement input. Both read tools request read authority for one exact database. Queries default to 100 rows and 1 MiB. Callers may request up to 1,000 rows and 4 MiB. Schema inspection is capped at 500 objects and 1 MiB. Limits are sent to the node and verified again by the MCP operation; excess results fail rather than being silently truncated. SQL BLOB parameters use { "type": "blob", "base64": "..." }; BLOB results add byteLength to the same tagged representation.

SQLite writes

tinycloud_sql_execute is a destructive, non-idempotent tool. It accepts exactly one INSERT, UPDATE, or DELETE, requires at least one positional ? placeholder, and requires one params value per placeholder. It rejects literal-only mutations, CTEs, DDL, pragmas, attachments, and multiple statements. The input must also set acknowledgeDatabaseWideAuthority: true.

{
  "space": "<SPACE_URI>",
  "database": "notes",
  "sql": "UPDATE notes SET body = ? WHERE id = ?",
  "params": ["reviewed", 42],
  "acknowledgeDatabaseWideAuthority": true
}

Approving tinycloud.sql/write grants full read, write, and schema-mutation authority over the exact database. The capability is not scoped to the table, row, statement, or mutation types accepted by tinycloud_sql_execute. The MCP tool enforces its narrower DML contract, but the delegation can authorize broader database operations when used outside that tool. Grant it only when database-wide authority is acceptable.

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

Delegated secret flow

Call tinycloud_secrets_get with the secret name and scope.
If the result is authority_required, use its structured request and approval action to obtain the exact capabilities. The server never silently falls back to owner authority.
In local stdio, import the approved delegation with tinycloud_auth_import. Hosted mode imports it through the OpenKey approval callback instead.
Retry tinycloud_secrets_get. Requests are persisted so approval and retry can happen in separate client sessions.
If the result is setup_required, follow its Secret Manager action to add the missing value, then retry.

Secret values appear only in the structured result, not in the text result, TinyCloud logs, errors, request files, or delegation files. Your MCP client may retain structured results in its own transcript, so use a client and retention policy appropriate for secrets.

Owner profiles

Owner-profile data access is disabled by default. To opt in, select the profile explicitly and pass both flags:

{
  "mcpServers": {
    "tinycloud-owner": {
      "command": "tinycloud-mcp",
      "args": ["--profile", "owner", "--allow-owner-profile"]
    }
  }
}

Use this mode only when the MCP host should have the owner’s full authority. Omitting either flag keeps owner data execution closed.

CLI

Hosting

OpenKey

Support

Connect Claude web, iOS or Android

Keep personal records naturally

Requirements

Configure local stdio

Available tools

KV data safety

SQLite reads

SQLite writes

Delegated secret flow

Owner profiles

​Connect Claude web, iOS or Android

​Keep personal records naturally

​Requirements

​Configure local stdio

​Available tools

​KV data safety

​SQLite reads

​SQLite writes

​Delegated secret flow

​Owner profiles

​Related CLI workflows

Connect Claude web, iOS or Android

Keep personal records naturally

Requirements

Configure local stdio

Available tools

KV data safety

SQLite reads

SQLite writes

Delegated secret flow

Owner profiles

Related CLI workflows