Skip to main content
Run the hosted MCP server when remote clients need a public Streamable HTTP endpoint. It is an OAuth resource server, not an owner authority: every tenant gets a separate generated session key and can use only capabilities approved through OpenKey.

​
Container

Terminate TLS at a reverse proxy and preserve the public Host header. The service refuses unexpected hosts and requires HTTPS for non-local public URLs.

​
Configuration

Keep the state secret stable. Rotating it intentionally disconnects existing OAuth subjects from their stored delegates. Back up the state volume and encrypt it at rest; it contains delegate private keys and signed capabilities, but no owner keys or OAuth access tokens. The production docker-compose.phala.yml explicitly sets TC_MCP_DELEGATION_EXPIRY=30d and TC_MCP_APPROVAL_TTL_SECONDS=900; the standalone container command above does not inherit those compose overrides. Expired or missing sessions return a fresh connect approval link in error.details; expired or missing grants return an authority_required approval link. The owner must approve again. Hosted mode exposes 20 tools, including tinycloud_connect and four tinycloud_apps_* tools. Local stdio has 17 tools; tinycloud_auth_import and tinycloud_secrets_status are local-only. Personal-record operations use one get/list/put/delete prefix grant for xyz.tinycloud.agent-data/ in default. This is an apps-specific exception, not broader authority for generic KV tools. The optional fast copy has a separate exact-database approval. KV remains the source of truth; COPY_PARTIAL resumes on the next query, while nonretryable NODE_ERROR with error.details.reason: "copy_unavailable" requires the node team, not a retry loop. See TinyCloud MCP for the owner workflow, ETag edits and partial write outcomes.

​
Scaling boundary

The filesystem store supports one service replica. It uses async-scoped tenant roots and per-profile locks inside that replica, but does not provide a distributed key-creation or approval transaction. Do not point multiple replicas at the same volume. A multi-replica deployment needs a shared transactional state provider.

​
OAuth requirements

The OpenKey issuer must allow:
  • Dynamic client registration for remote MCP clients
  • The tinycloud:mcp scope
  • The exact TC_MCP_PUBLIC_URL as an OAuth resource audience
  • The https://tinycloud.xyz/owner_dids access-token claim
The MCP resource validates signature, issuer, audience, expiry, and scope on every request. The browser approval callback is short-lived, HMAC-bound, single-use, and cryptographically validated by the TinyCloud SDK before the delegation is persisted. The approval page names the account that asked, and the callback refuses a delegation signed by any other account with 403 approval_owner_mismatch (@tinycloud/mcp 0.3.3 and later).

​
Results and privacy

Hosted text blocks include the canonical JSON result so clients that ignore structuredContent can still read records and approval links. Successful secret values remain structured-only. Read-only results over 100,000 characters return a nonretryable size error with narrowing guidance; write results are never truncated by this cap. Writes do not use an operation deadline that could abandon reporting while a mutation continues. Each tool call emits one stderr line containing only the tool name, outcome code, duration and successful replayed-grant count. Never log keys (which can contain personal slugs), values, catalog text, SQL or parameters.
The service processes plaintext inputs and results, including delegated secrets. Treat its runtime and observability pipeline as part of the data trust boundary. Do not log request bodies, text result blocks or structured tool results.