TinyCloud MCP

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

Connect Claude web or mobile

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 to the 16 canonical tools. 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.

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
@tinycloud/mcp 0.3.0 or newer for hosted mode; 0.2.0 or newer for local stdio
A TinyCloud node running 1.6.0 or newer
An MCP client that supports structured tool results

The node release must be deployed before the stable MCP package is published; this 16-tool documentation is published only after both are available.

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

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. Every data operation plans authority for the exact space and key, prefix, or database in its input. 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.

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.
Import the approved delegation with tinycloud_auth_import.
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 or mobile

Requirements

Configure local stdio

Available tools

KV data safety

SQLite reads

SQLite writes

Delegated secret flow

Owner profiles

​Connect Claude web or mobile

​Requirements

​Configure local stdio

​Available tools

​KV data safety

​SQLite reads

​SQLite writes

​Delegated secret flow

​Owner profiles

​Related CLI workflows

Connect Claude web or mobile

Requirements

Configure local stdio

Available tools

KV data safety

SQLite reads

SQLite writes

Delegated secret flow

Owner profiles

Related CLI workflows