{"name":"dev.homespun/homespun","slug":"homespun","title":"Homespun","description":"Deploy a multi-user web app from your agent: hosting, auth, database, and permissions.","url":"https://mcp.market/server/homespun","rating":null,"grade":"B","score":79,"certified":false,"status":"active","category":"data","tags":["data","devtools","ai","security"],"presence":{"score":26,"stars":1,"forks":0,"downloads_week":null,"last_push_at":"2026-09-13T14:50:48.000Z","license":"MIT"},"uptime":{"percent":100,"checks":1,"ok":1,"last_checked_at":"2026-09-19T16:30:34.245Z","last_ok_at":"2026-09-19T16:30:34.245Z","latency_ms":483},"claimed":false,"transport":"mixed","callable_via_gateway":true,"default_price_micros":0,"repository":"https://github.com/homespunapps/homespun","website":"https://homespun.dev","version":"1.6.89","remotes":[{"type":"streamable-http","url":"https://homespun.dev/mcp"}],"packages":[{"registryType":"npm","registryBaseUrl":"https://registry.npmjs.org","identifier":"@homespunapps/mcp","version":"1.6.89","transport":{"type":"stdio"},"environmentVariables":[{"description":"Homespun agent API key. If unset, the server auto-registers a fresh agent against the relay on first use and saves the key to the shared CLI store (~/.config/homespun/config.json).","isSecret":true,"name":"HOMESPUN_API_KEY"},{"description":"Homespun relay base URL. Defaults to the hosted relay https://homespun.dev; set this to point at a different relay.","name":"HOMESPUN_URL"},{"description":"Display name for the auto-registered agent on the relay.","name":"HOMESPUN_AGENT_NAME"},{"description":"Registration secret, required only for relays running REGISTRATION_MODE=secret.","isSecret":true,"name":"HOMESPUN_REGISTER_SECRET"}]}],"tools":[{"name":"agent","description":"Agent identity and binding. Actions: whoami returns the resolved relay URL, the active profile and whether a key is configured, with no network call and no secrets; claim binds this agent to a human using a one-shot claim code from their Settings UI, and is one-way; logout clears the locally saved key and profile but does not revoke it on the relay, which is what the `key` tool's revoke action does.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"action":{"type":"string","enum":["whoami","claim","logout"],"description":"Agent identity. whoami: show the resolved relay URL, active profile, and whether a key is configured (no network, no secrets). claim: bind this agent to a human via a one-shot claim code the human generated in their Settings UI (one-way). logout: clears the locally-saved key/profile; the key is not revoked on the relay, which is what the key tool's revoke action does."},"code":{"description":"The one-shot claim code (required for claim).","type":"string"}},"required":["action"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"apps","description":"The v2 app lifecycle apart from creation and redeploy, which deploy_app covers. Actions: list returns the owning human's apps; show returns full detail including manifest, timezone and has_share_token; audit is a read-only security review of every app the caller owns, computed from each app's stored manifest, which is what makes it see apps that were deployed once and never redeployed (a deploy-time warning never reaches those). It reports collections whose declared permissions expose them, worst first: severity 'high' means an anonymous visitor can exploit it today, typically a collection that admits \"anyone\" to write with no separate 'update' list, so any visitor can overwrite rows other people created rather than only adding their own. It changes nothing; the fix is a redeploy declaring the missing list, and the right list differs per app, so read the app before proposing one. update changes visibility and timezone, the slug being immutable, and switching to 'link' returns a share_url once; share_link_rotate issues a new share token for a 'link' app, returning a new share_url and revoking the old link, and generates one if the app has none; delete is an idempotent soft-delete, and it is recoverable: the app stops serving at once but keeps every version, collection, row, attachment, member and grant, and restore brings all of it back until the retention window elapses (list_deleted shows what is in the trash and each app's purges_at deadline, which is null when the account is never purged). restore is idempotent on a live app, and refuses with 409 when the account is at its app limit, when the app was an expired trial, or when the owning account is itself deleted; an app an operator suspended comes back suspended, not active. purge destroys a deleted app and all its data immediately and forever, with no restore afterwards, and requires the app to already be deleted, so no single call takes a serving app to unrecoverable; wake wakes a dormant app and is otherwise a no-op that reports the actual status; domain_set binds a custom domain and returns the DNS records the domain owner must publish, where the first domain bound serves the app and every later one redirects to it, which is how apex plus www is configured; domain_status returns the serving domain and its `aliases`, live-refreshed against Cloudflare when that is enabled, with last_error carrying the reason a domain is not activating; domain_remove unbinds one domain, or all of them when no `domain` is given, and is idempotent.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"action":{"type":"string","enum":["list","show","audit","update","share_link_rotate","delete","list_deleted","restore","purge","wake","domain_set","domain_status","domain_remove"],"description":"list: the caller's owning human's apps. show/update/delete/wake: act on one app (app_id). audit: read-only security review of every app the caller owns. share_link_rotate: rotate a 'link' app's share token, returning a new share_url (the old link stops working); also generates one if the app has none yet. list_deleted: the apps in the trash, each with when it is purged for good. restore: bring a deleted app back with all its data (app_id). purge: destroy a deleted app forever, now (app_id). domain_set/domain_status/domain_remove: manage the app's custom domains (app_id; domain_set also needs domain)."},"severity":{"description":"audit only. Return findings of this severity only. The response's `counts` always describe the whole audit, so filtering never hides that other findings exist.","type":"string","enum":["high","medium","low"]},"app_id":{"description":"Required for show/update/share_link_rotate/delete/restore/purge/wake/domain_set/domain_status/domain_remove.","type":"string"},"status":{"description":"list only. Default: active. 'all' means every live status; deleted apps are never in this list, use action list_deleted for those.","type":"string","enum":["active","dormant","archived","suspended","all"]},"limit":{"description":"list only. Page size.","type":"integer","exclusiveMinimum":0,"maximum":200},"cursor":{"description":"list only. Opaque cursor from a previous next_cursor.","type":"string"},"slug":{"description":"list only. Exact-match slug filter.","type":"string"},"visibility":{"description":"update only. The new visibility (slug is immutable).","type":"string","enum":["private","link","public"]},"timezone":{"description":"update only. The app's IANA timezone for `schedules` reminders (e.g. Europe/Berlin). An app that declares schedules with no timezone fires reminders at 08:00 UTC.","type":"string"},"domain":{"description":"domain_set: the bare custom domain to bind (e.g. app.example.com); the response's dns_records lists the DNS entries the domain owner must publish. domain_remove: optional, the one domain to unbind - omit it to unbind them all.","type":"string"}},"required":["action"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"attachments","description":"Binary attachments (images, PDFs, audio, video) referenced from event payloads and input_data via `format: homespun-attachment-id`. Actions: upload, fetch, presign, finalize, download, show, list, delete, mint_token, revoke_token, list_tokens.\n\nChoosing an upload path matters for cost. An inline upload with `content_base64` carries the bytes in the tool-call arguments, so they enter the model context at a token cost proportional to file size, paid again on every retry; a few-hundred-KB image is already expensive. Two paths avoid that entirely: fetch, when the bytes are reachable at a URL, and presign plus finalize, when the client can PUT the raw bytes out of band. Inline upload suits small assets and clients that have neither a URL nor an out-of-band PUT.\n\nfetch takes { source_url (https), scope } and the relay downloads the URL itself behind an SSRF guard (https only, no private, loopback or metadata hosts, DNS pinned, redirects refused, size-capped and timed out), then runs the same byte-sniff, allowlist, size, quota and scan checks as any upload. It works on any storage backend. upload takes either `content_base64` (base64 bytes, no filesystem) or `file_path` (an absolute path read on the relay host, so it only applies when the file is local to the relay). presign plus finalize is token-free: presign with { mime, size, sha256, scope } returns { put_url, attachment_id }, the caller PUTs the raw bytes to put_url over plain HTTP out of band, then finalize with the attachment_id. At finalize the relay re-reads the stored bytes, sniffs the real type, and enforces the same allowlist, size, sha256, quota and scan checks, so a presign that misstates its mime is caught and never served inline. The presigned path requires the Azure storage backend; a filesystem-backed relay returns a clear not-supported error and fetch or inline upload apply there instead. download writes to an absolute out_path or returns base64. An upload is scoped to agent (the default, reusable) or app. mint_token returns a /b/ capability URL, shown once, that a browser can GET without the caller's API key.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"action":{"type":"string","enum":["upload","fetch","presign","finalize","download","show","list","delete","mint_token","revoke_token","list_tokens"],"description":"Binary attachment operations. The upload path affects token cost: `fetch` and presign plus finalize keep the bytes out of the model context entirely, while upload with `content_base64` carries them in the tool-call arguments at a cost proportional to file size, paid again on every retry. fetch takes { source_url, scope } and the relay downloads the bytes itself (https only, SSRF-guarded), running the same sniff, allowlist, size, quota and scan checks as any upload. upload takes `content_base64` (base64 bytes, no filesystem) or `file_path` (absolute, read on the relay host), scoped agent or app. presign plus finalize is three steps: presign with { mime, size, sha256, scope }, PUT the bytes to put_url out of band, then finalize, which re-sniffs and re-checks them. download fetches bytes by attachment_id to an absolute out_path or returns base64. show returns metadata only. list returns the agent's attachments. delete is a soft-delete. mint_token mints a /b/ capability URL, returned once. revoke_token and list_tokens manage those tokens."},"size":{"description":"presign: the exact byte length you will PUT. Committed at presign and re-verified against the uploaded bytes at finalize.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"sha256":{"description":"presign: the hex SHA-256 (64 chars) of the exact bytes you will PUT. Committed at presign and re-verified against the uploaded bytes at finalize.","type":"string"},"attachment_id":{"description":"Attachment id. Required for download/show/delete/mint_token/revoke_token/list_tokens.","type":"string"},"file_path":{"description":"upload: absolute path to a file read on the server host running this MCP connector (the relay), not the calling agent's machine. It resolves only when the file is local to the relay (e.g. a locally-run CLI); a hosted or remote agent supplies the bytes as `content_base64` instead.","type":"string"},"source_url":{"description":"fetch: an https URL the relay downloads server-side, so the bytes do not enter the model context and cost no tokens. SSRF-guarded: https only, no private, loopback, link-local or metadata hosts, DNS pinned, redirects refused, size-capped and timed out. The downloaded bytes run the same byte-sniff, allowlist, size, quota and scan checks as any upload. This and presign plus finalize are the zero-context paths for real images and media.","type":"string"},"content_base64":{"description":"upload: the file bytes as base64, sent inline with no filesystem access. The base64 rides in the tool-call arguments and enters the model context, costing tokens proportional to file size; a few-hundred-KB image is already expensive, and the cost repeats on every retry. presign plus finalize avoids that for any real image or media whenever the client can do an out-of-band HTTP PUT, which leaves `content_base64` suited to small assets such as a tiny icon, and to clients that cannot PUT out of band. If both `content_base64` and `file_path` are given, `content_base64` wins. The relay sniffs the real type and enforces the same size, allowlist and quota checks as a file upload.","type":"string"},"scope":{"description":"upload scope (default agent).","type":"string","enum":["agent","app"]},"app_id":{"description":"Required when scope=app.","type":"string"},"filename":{"description":"upload: display filename (defaults to the file's basename).","type":"string"},"mime":{"description":"upload/presign: advisory Content-Type. The relay byte-sniffs the actual bytes and stores/serves that sniffed type regardless (a lying mime is caught, never served inline). Required for presign (scopes the upload URL + fails fast against the allowlist).","type":"string"},"out_path":{"description":"download: absolute path to write the bytes to. If omitted, the bytes are returned base64-encoded in the result.","type":"string"},"cursor":{"description":"list pagination cursor.","type":"string"},"limit":{"description":"list page size (1..100).","type":"integer","exclusiveMinimum":0,"maximum":100},"ttl_seconds":{"description":"mint_token: per-token TTL (clamped by scope default).","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"once":{"description":"mint_token: token self-deletes on first GET.","type":"boolean"},"token_id":{"description":"revoke_token: the token id to revoke.","type":"string"}},"required":["action"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"community","description":"Publishing an app as a community template, taking your own listing back down, installing a template, and, for relay operators, reviewing submissions. Actions: publish, unpublish, get_config_contract, install, list_pending, get_submission, approve, reject, set_trust_level.\n\npublish captures a live app (html, manifest, the seed rows of its seedOnInstall collections, and listing metadata) into a pending template. It is installable by the returned direct link but is not listed in the public gallery until an operator approves it, and it requires a verified email and no more than a few pending submissions at once. Privacy consequence: an approved template's content and its captured seed rows become public to every platform user, so seed data in a published app must be example-only rather than real personal data. attest_example_only:true records that this was checked. A template may take a per-publisher `slug` (namespaced as /) and a semver `version` defaulting to 1.0.0, and a republish under the same slug must bump the version.\n\nunpublish is the publisher's own undo for a live listing, taken down by snapshot_id: it leaves the public gallery, search, and the direct snapshot install link. It works only on your own submissions, and a snapshot that does not exist or belongs to someone else reads as not found either way. Existing installs are unaffected, because an install is a fresh private copy rather than a live reference, so unpublishing never breaks an app someone already installed. It is idempotent, and publishing a new version is the way to put the listing back.\n\nget_config_contract reads what a template needs at install, meaning its settings collection and its ordered config and upload steps, by `ref`. install creates a fresh private copy of a template for the caller's owning human, passing answers as `config`, where a 'config' value is a string and an 'upload' value is a pre-uploaded attachment id from the attachments tool.\n\nThe review actions are limited to the relay's configured community reviewers: list_pending returns the queue; get_submission returns a submission's full content by snapshot_id; approve lists it in the gallery, where a re-publish supersedes the app's prior approved version; reject takes a required note that lands in the publisher's app feed.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"action":{"type":"string","enum":["publish","unpublish","get_config_contract","install","upgrade_check","upgrade","revert","list_pending","get_submission","approve","reject","set_trust_level"],"description":"publish: publishes one of the caller's apps as a community template (app_id; optional title/description/category/tags). Privacy consequence: publishing makes the template content and the captured seed rows (the live rows of every seedOnInstall collection, captured at publish time) public to every platform user once approved, so an app whose seedOnInstall collections hold real personal data (names, emails, addresses, messages, anything private) is not safe to publish: seed data must be example-only. attest_example_only:true records that this was checked. The capture (html + manifest + seed rows) lands pending review, installable by its returned direct link but not listed until approved; an established publisher is fast-tracked, and the response's expedited/auto_approved fields report which path it took. unpublish: takes one of the caller's own published templates back down (snapshot_id). It removes the listing from the public gallery, from search, and from the direct snapshot install link. Existing installs keep working untouched, because an install is a fresh private copy rather than a live reference. It is idempotent (unpublishing an already-unpublished template is a no-op), and a snapshot that does not exist or belongs to someone else reads as not found either way. Publishing a new version is what puts the listing back. get_config_contract: read a template's install-time config contract by `ref` (a namespaced '/' or a snapshot id): its settings_collection, ordered config_steps (each with key/kind/required/secret/choices/default), and connect_steps (inbound hooks the app receives on). An 'upload' step wants a file, pre-uploaded with the attachments tool (scope agent) and passed as its attachment id. A template installed with connect_steps provisions hook URLs, which the `ingest` tool's list action returns for the new app_id, ready to wire into the external service. install: installs a template by `ref` for the caller, whose owning human becomes the owner. `config` is { stepKey: value } from the contract: a 'config' step's value is a string, an 'upload' step's value is a pre-uploaded attachment id. An omitted required step is rejected. Returns the new app's id, slug, and url; installs always create a fresh private copy. list_pending / get_submission / approve / reject / set_trust_level are relay-operator-only review actions: list_pending (the review queue, expedited submissions first), get_submission (a submission's full html+manifest+seedRows plus external_destinations, the hosts it can send data to or pull data from, by snapshot_id), approve (snapshot_id, lists it in the gallery + supersedes the app's prior approved version), reject (snapshot_id + a required note that lands in the publisher's app feed), set_trust_level (promote/demote a publisher by handle: handle + trust_level 'new'|'established').\n\nupgrade_check / upgrade / revert keep an already-installed app current with its source template (app_id). An install is a one-shot fork, so nothing updates on its own and there is no follow/pin: you have to ask. upgrade_check reports whether a newer live version of that app's template line exists, whether it would apply cleanly, and what it would newly be allowed to reach. upgrade applies it in place, keeping the app's address, collections and rows, and landing as a new version you can undo. It refuses outright, with no override, when the new version would strand rows the app already holds; when the new version merely asks for more than the installed one, pass accept_permissions:true, but only after showing the owner what `permission_lines` says. revert puts the app back on the version it ran before the last update, and refuses when rows written since would have nowhere to live under the older one."},"ref":{"description":"get_config_contract/install only. The template to read or install: a namespaced '/' or a community snapshot id.","type":"string"},"config":{"description":"install only. The install-time answers as { stepKey: value } from the config contract: a 'config' step's value is a string, an 'upload' step's value is a pre-uploaded attachment id. Omit for a template with no config steps.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"app_id":{"description":"publish / upgrade_check / upgrade / revert. For publish, the app to publish. For the three upgrade actions, the installed app to act on: an installed template is a fork, so the question is whether a newer version of the template that app came from exists, which only the app can answer.","type":"string"},"accept_permissions":{"description":"upgrade only. Required when upgrade_check reports a non-empty `permissions` diff, meaning the new version asks for more than the installed one (new hosts it can send data to, new device capabilities, a service worker, CDN scripts). Never assume it: show the owner `permission_lines` and set this only once they have agreed. It does not clear a version that would strand rows, which nothing can.","type":"boolean"},"expect_version":{"description":"upgrade only. The version upgrade_check reported. When given, the upgrade is refused if the offer has moved since, so a publisher shipping again mid-flight cannot slip a version past you that you never showed anyone.","type":"string"},"title":{"description":"publish only. Listing title (1 to 80 chars). Defaults to the app's manifest name.","type":"string"},"description":{"description":"publish only. Listing blurb (up to 200 chars). Defaults to the manifest description.","type":"string"},"long_description":{"description":"publish only. Optional long-form description (up to 4000 chars) shown on the template detail page below the short blurb, for readers and search ranking. Plain text: blank lines become paragraphs, and it is escaped (never rendered as raw HTML), so write prose, not markup.","type":"string"},"category":{"description":"publish only. Optional single-word category (e.g. 'household').","type":"string"},"tags":{"description":"publish only. Up to 6 curation tags.","type":"array","items":{"type":"string"}},"slug":{"description":"publish only. Optional per-publisher slug (lowercase, 3 to 48 chars, hyphens). Gives the template a namespaced id /; a republish reuses the slug and must bump the version. If omitted, a slug is derived from the title instead of leaving the template unnamed, so this field matters only when a specific url is wanted. Slugs are immutable: renaming the template later does not move its url, so the slug chosen here is permanent.","type":"string"},"version":{"description":"publish only. Semver MAJOR.MINOR.PATCH (default '1.0.0'). A republish under the same slug must be strictly greater than the current version.","type":"string"},"changelog_note":{"description":"publish only. A short note recorded in this version's changelog.","type":"string"},"setup_steps":{"description":"publish only. Ordered typed setup steps an installing agent follows after install (up to 20). A 'config'/'upload' step may carry a `key` naming a field of the manifest's settingsCollection that its install-time answer is written into; a 'connect' step may carry an `ingestRule` naming a manifest ingest rule it wires up. Read back via get_submission and rendered on the template detail page.","type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["config","seed-data","connect","note","upload"],"description":"config = set a value; upload = an install-time file/image the app stores as an attachment id; connect = wire up an external data source; seed-data = review/replace captured starter data; note = a plain instruction."},"label":{"type":"string","description":"Short step label (<= 80 chars)."},"key":{"description":"The settings-collection field this answer is written into (letters, digits, '_', up to 64 chars). Required for an 'upload' step, optional for a 'config' step, not allowed on the others. Must name a declared top-level field of the manifest's x-homespun-manifest.settingsCollection; an 'upload' target must be a string-typed field.","type":"string"},"description":{"description":"Optional longer instruction (<= 300 chars).","type":"string"},"required":{"description":"Whether this step is required (default false).","type":"boolean"},"secret":{"description":"Mark a step whose value is sensitive (an API key/token). Its default is MASKED on the public detail page; publish only your own example default, never a real secret.","type":"boolean"},"default":{"description":"Optional example/default value (<= 200 chars).","type":"string"},"choices":{"description":"Optional list of allowed values (up to 12).","type":"array","items":{"type":"string"}},"valueHint":{"description":"Optional format hint (<= 120 chars).","type":"string"},"ingestRule":{"description":"The manifest `ingest` rule this step wires up. Allowed only on a 'connect' step, and optional there; publish rejects a name that x-homespun-manifest.ingest does not declare. Each install mints that rule its own hook URL, which the installer pastes into the external service.","type":"string"}},"required":["kind","label"]}},"derived_from_snapshot_id":{"description":"publish only. Optional remix/fork lineage: the snapshot id this template was derived from.","type":"string"},"attest_example_only":{"description":"publish only. True attests that the template content and the captured seed rows contain no real personal data. Publishing makes both public to every platform user, so seed data (the live rows of the app's seedOnInstall collections) must be example-only, never real names/emails/addresses/private messages. Recorded and shown to the reviewer; omitting it still publishes but is flagged to the operator as not attested.","type":"boolean"},"snapshot_id":{"description":"Required for get_submission/unpublish/approve/reject. The submission's snapshot id (from publish's response or list_pending).","type":"string"},"note":{"description":"reject only. The required rejection note shown to the publisher (delivered to their app feed).","type":"string"},"limit":{"description":"list_pending only. Page size (1..200).","type":"integer","exclusiveMinimum":0,"maximum":200},"cursor":{"description":"list_pending only. Opaque cursor from a prior next_cursor.","type":"string"},"handle":{"description":"set_trust_level only. The @-handle of the publisher to promote or demote.","type":"string"},"trust_level":{"description":"set_trust_level only. 'established' fast-tracks the publisher's future submissions through review; 'new' reverts to full review.","type":"string","enum":["new","established"]}},"required":["action"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"connections","description":"A v2 app's Connections: the stored credential (a static header token, or a full generic OAuth2 client) a manifest webhook rule authenticates its delivery target with, bound to a host so the credential can never be exfiltrated to another one. There is no update action: change a connection by deleting and recreating it. Actions: create stores a static or oauth2 connection and returns its metadata, never the secret; list returns the app's connections as metadata plus a non-reversible fingerprint, never any secret; delete is idempotent; consent_url builds (never fetches) the browser URL that completes an oauth2 connection's consent, since that is inherently a human-in-a-browser step an agent key cannot complete. A newly created oauth2 connection starts in `pending_auth` until the owner opens the consent_url and approves.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"action":{"type":"string","enum":["create","list","delete","consent_url"],"description":"create: store a webhook connection, a stored credential (static header token or a full generic OAuth2 client) a manifest webhook rule authenticates its target with (app_id+name+allowed_host, plus kind-specific fields). list: the app's connections as metadata plus a non-reversible fingerprint, never any secret (app_id). delete: idempotent (app_id+name). consent_url: build (never fetch) the browser URL that completes an oauth2 connection's owner consent (app_id+name); hand it to the signed-in owner to open, since an agent key cannot complete OAuth consent itself."},"app_id":{"type":"string","minLength":1,"description":"The app id."},"name":{"description":"create / delete / consent_url. The connection name (lowercase, starting alphanumeric, up to 64 chars) that a manifest webhook rule's `connection` field references.","type":"string"},"kind":{"description":"create only. Defaults to `static`.","type":"string","enum":["static","oauth2"]},"provider":{"description":"create only. Freeform display label only, e.g. \"hubspot\"; not validated against any allowlist.","type":"string"},"label":{"description":"create only. Optional owner-facing label.","type":"string"},"allowed_host":{"description":"create only, required for both kinds. The host-binding exfiltration defence: an exact DNS host (\"api.hubapi.com\") or a single leftmost wildcard (\"*.zohoapis.com\"). The stored credential is attached to a delivery only when its url host matches; a rule later repointed elsewhere fails delivery rather than sending the secret to the wrong host.","type":"string"},"header_name":{"description":"create only (static). The header the credential rides in. Defaults to \"Authorization\".","type":"string"},"header_value":{"description":"create only, required for kind=static. The header value to send, e.g. \"Bearer sk_live_...\". Encrypted at rest and never returned by any call.","type":"string"},"authorize_url":{"description":"create only, required for kind=oauth2. The provider's OAuth2 authorize endpoint (https; rejected if it resolves to a private/loopback/metadata address).","type":"string"},"token_endpoint":{"description":"create only, required for kind=oauth2. The provider's OAuth2 token endpoint (same https + SSRF rules as authorize_url).","type":"string"},"client_id":{"description":"create only, required for kind=oauth2. Your OAuth2 app's client id.","type":"string"},"client_secret":{"description":"create only, required for kind=oauth2. Your OAuth2 app's client secret. Encrypted at rest and never returned by any call.","type":"string"},"scopes":{"description":"create only (oauth2). Space-delimited scopes for the authorize request.","type":"string"},"auth_scheme":{"description":"create only (oauth2). The scheme the access token is sent under. Defaults to \"Bearer\"; set e.g. \"Zoho-oauthtoken\" for a non-Bearer provider.","type":"string"},"instance_field":{"description":"create only (oauth2). The name of a token-response JSON field holding the API base URL (e.g. \"instance_url\"). When set, the relay re-binds allowed_host to that host after consent and resolves relative rule urls against it.","type":"string"},"auth_params":{"description":"create only (oauth2). Extra key/values merged into the authorize redirect (e.g. to request offline access).","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"token_params":{"description":"create only (oauth2). Extra key/values merged into the token POST.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["action","app_id"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"count_rows","description":"The live row count of a v2 app's collection (spec B4, issue #1056), a whole-scope total with no filter and no paging. Gated by the collection's countRead opt-in, independent of its read list: a collection that opted in returns its count even to a caller who cannot list the rows (the '3 spots left' shape), and a collection that never opted in refuses with collection_count_forbidden even for a caller who could otherwise list. Returns { count }.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"app_id":{"type":"string","minLength":1,"description":"The app id."},"collection":{"type":"string","minLength":1,"description":"The collection name declared in the app's manifest."}},"required":["app_id","collection"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"credentials","description":"A v2 app's scoped service credentials (#1354, #1355): the bearer token an app owner points a backend they host themselves at, so their own server can read and write the app's data without holding the owner's full authority. Effective permission is always the intersection of the allowlist and what the app's owner could do, so a credential can only ever narrow, never widen, and it carries no role. Actions: mint creates one and returns its raw `token` shown once, never recoverable afterward (only its hash is stored); list returns the app's credentials with their allowlist and status, never any token material; pause reversibly stops one; resume undoes a pause (never a revoke, which is permanent); rotate issues a fresh token while the old one keeps working for an overlap window, so a running backend picks up the new token with no outage; revoke kills one permanently. Every action here is owner-or-owning-agent only: a service credential itself can reach none of these, by construction, so it can never mint or widen a sibling of itself.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"action":{"type":"string","enum":["mint","list","pause","resume","rotate","revoke"],"description":"mint: create a scoped service credential, the bearer token an app owner points a backend they host themselves at (app_id; optional mode/grants/members/label/ttl_seconds). list: the app's credentials, their allowlist and status, never a token (app_id). pause: reversibly stop one, in force on its very next request (app_id+credential_id). resume: undo a pause; never undoes a revoke, which is permanent (app_id+credential_id). rotate: issue a fresh token and keep the old one working for an overlap window so a running backend picks it up without a gap (app_id+credential_id; optional overlap_seconds). revoke: kill one permanently and idempotently (app_id+credential_id)."},"app_id":{"type":"string","minLength":1,"description":"The app id."},"mode":{"description":"mint only. Defaults to explicit: an unnamed collection is denied, so the credential can never reach anything it was not handed (the shape for a contractor's backend). following: an unnamed collection falls through to the owner's own authority, so the credential tracks the app as it grows and each `grants` entry only narrows one collection (the shape for the owner's own backend). Neither mode can ever exceed what the app's owner could do; the effective permission is always the intersection.","type":"string","enum":["explicit","following"]},"grants":{"description":"mint only. The allowlist: one entry per collection naming which of read/create/update/delete this credential may attempt there (an entry may name zero ops, which under `following` is how one collection is carved out of an otherwise app-wide credential). A collection named here must be a real declared collection on the app; a typo is rejected with a 400 rather than silently doing nothing.","type":"array","items":{"type":"object","properties":{"collection":{"type":"string","minLength":1},"ops":{"type":"array","items":{"type":"string","enum":["read","create","update","delete"]}},"scope":{"description":"Narrows every row-addressed op to rows this credential itself wrote last. Inert for create.","type":"string","const":"own"}},"required":["collection","ops"]}},"members":{"description":"mint only. Opt in to the app's member directory appearing in this credential's boot/hello payloads. Defaults to false: a credential that never learns a member id cannot stamp one into a relation field.","type":"boolean"},"label":{"description":"mint only. Optional owner-facing label shown in the credential list.","type":"string"},"ttl_seconds":{"description":"mint only. Omit for the server's bounded default (365 days, clamped to a server maximum). null means no expiry, the explicit opt-in a long-running backend asks for; it is never the default.","anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]},"credential_id":{"description":"pause / resume / rotate / revoke. The credential id (see list's `id` field).","type":"string"},"overlap_seconds":{"description":"rotate only. How long the superseded token keeps resolving, so a running backend can pick up the new one with no gap. Defaults to the server default (1 day); 0 kills the old token immediately, the \"this leaked\" case.","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["action","app_id"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"delete_row","description":"Soft-delete a row from a v2 app's collection. Recoverable: the row is tombstoned, not destroyed, and restore_row brings it back for 30 days (see list_deleted_rows). A watcher sees the deletion live as op:delete on the change feed. Pass if_match for an optimistic-locked delete. Returns { deleted: true }.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"app_id":{"type":"string","minLength":1,"description":"The app id."},"collection":{"type":"string","minLength":1,"description":"The collection name."},"key":{"type":"string","minLength":1,"description":"The key of the row to delete."},"if_match":{"description":"Optional optimistic-lock version.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["app_id","collection","key"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"deploy_app","description":"Deploy a v2 app: an HTML document plus a capability manifest, hosted at its own URL.\n\nA redeploy only needs the content that changed. Every content field is optional when `app_id` is given, and an omitted one keeps what is live: omit `manifest` for an HTML-only change, omit `html` for a manifest-only change, omit `assets` to keep the current files. This is the cheap path and the default, because an omitted field costs no output tokens at all: a one-line colour change does not resend the whole document, and a manifest edit does not resend it either. A field only needs sending when its content differs from what is live. `assets: []` is the explicit way to clear the asset set, and omitting all three is refused, since there would be nothing to change.\n\nThe extension keys used most often: app metadata; collections, with per-collection write, update, read and delete role lists, where write gates creates and also gates updates unless an update list is declared; externalHosts, a fetch allowlist; cdn, to allow CDN scripts and styles; capabilities, for Permissions-Policy opt-ins; embeds, an iframe frame-src allowlist; notify, for email-on-row rules; webhooks, for signed HTTP POST on-row rules; and agentTasks, to queue work for an agent running on the owner's own machine, described as a prompt rather than as code. The manifest grammar is documented in the Homespun guide that get_skill returns.\n\nPass no `app_id` to create, which mints a slug and URL and requires both `html` and `manifest`, or pass `app_id` to redeploy an existing app. Supply the HTML inline as `html`, or as `html_path`, an absolute path read on the MCP-server host, which is the relay for a hosted connector or the CLI host for a locally-run one, and not the remote agent's machine; it avoids retransmitting a large HTML file on every deploy, only a locally-run connector can read it, and inline `html` wins if both are given. `dry_run:true` (alias `check`) validates only: it runs the full manifest and asset validation, the redeploy compat gate and the schedule-timezone advisory, then returns { ok, warnings, compat?, breaks? } without creating a version or mutating anything, and it resolves omitted fields the same way a real deploy would, so it reports on exactly the deploy that would run.\n\nA redeploy is refused with manifest_incompatible_redeploy, unless force:true, when it would strand rows already written (dropping a collection, tightening a schema, flipping appendOnly), or when it would widen what the app's install screen discloses: a collection's read reaching further than the live manifest, a capability added, cdn turned on, or a host added to externalHosts, embeds or a webhook target. The break quotes the sentence a user would now be asked to approve. Taking access away never prompts: dropping a role, dropping a capability, host or webhook, turning cdn off, or adding update:[\\\"creator\\\"] to a write:[\\\"anyone\\\"] collection, all redeploy clean. A removed collection is detached rather than deleted.\n\nImages, fonts, audio, video and data files ship with the app in the same call via `assets[]`. Each is validated and stored app-scoped and served at its `path` on the app's own origin, so the HTML references it by a stable same-origin path such as ``; media and font paths support HTTP Range for seeking. A redeploy's assets replace the previous version's set when sent, carry over when omitted, and are cleared by `assets: []`.\n\nReturns { app_id, slug, url, version, visibility, created } on create, or { app_id, version, compat, breaks? } on redeploy.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"app_id":{"description":"Omit to create a new app; pass an existing app's id to redeploy it (a new version, compat-gated unless force:true).","type":"string"},"html":{"description":"The app's UI as a complete HTML document (single file, with CSS and JS inline), sent inline. Capped at 2 MB of UTF-8; over that the deploy is refused with 413 document_size_exceeded. A document near the cap is almost always carrying a file inlined as a data: URI; the same file in `assets[]` is served from the app's own origin, cached separately, and does not count toward this cap. The document comes from either this field or `html_path`. Inline is the only form a hosted or remote connector with no filesystem can use, and inline `html` wins if both are given. On a redeploy an omitted `html` keeps the live document, so a manifest-only change (adding a collection, widening externalHosts) costs nothing in HTML.","type":"string","minLength":1},"html_path":{"description":"Absolute path to the app's HTML document, read on the MCP-server host (the machine running this connector: the relay for a hosted connector, or the CLI host for a locally-run one), not on the remote agent's machine. An alternative to inline `html` that avoids retransmitting a large HTML file on every deploy. It resolves only when the file is local to the MCP server, so it serves a locally-run connector rather than a hosted or remote one, where the path does not exist and the call returns a clean error; inline `html` is the form that works there. If both `html` and `html_path` are given, inline `html` wins.","type":"string"},"dry_run":{"description":"Validate only: run the full manifest + asset-shape validation, the compat gate (for a redeploy), and the schedule-timezone advisory, then return { ok, warnings, compat?, breaks? } without creating a version or mutating anything. An invalid manifest returns the same error a real deploy would; a redeploy the compat gate would refuse reports the break instead of applying it. `check` is an accepted alias.","type":"boolean"},"check":{"description":"Alias for `dry_run`.","type":"boolean"},"manifest":{"description":"The x-homespun-manifest capability document (a JSON object). Required to create; on a redeploy an omitted `manifest` keeps the live one, which fits most redeploys (the manifest was byte-identical to the previous version in 71% of real redeploys). The extension keys used most often: app metadata; collections (+ per-collection write/update/read/delete role lists, where write gates creates and also updates unless the optional update list is declared); externalHosts (fetch allowlist); cdn (allow CDN scripts/styles); capabilities (Permissions-Policy opt-ins); embeds (iframe frame-src allowlist); notify (email-on-row rules); webhooks (signed HTTP POST on-row rules); agentTasks (queue work for an agent on the owner's own machine, described as a prompt). The full grammar is documented in the Homespun guide that get_skill returns.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"visibility":{"description":"Create only. Default 'private' (owner plus invited members, sign-in gated). 'link' shares with anyone holding the returned share_url, whose #k= fragment carries a secret key that can be reset (rotate it via the apps tool, action share_link_rotate) to cut off everyone with the old link; a 'link' app always gets a server-generated unguessable slug. 'private' and 'public' accept an owner-chosen `slug`.","type":"string","enum":["private","link","public"]},"slug":{"description":"Create only. Accepted with visibility private or public, including the private default; rejected with explicit visibility 'link', where the slug is always server-generated.","type":"string"},"force":{"description":"Redeploy only. Bypasses the compat gate, whether it fired on a stranded-rows narrowing or on a widening of what the install screen discloses (a removed collection is detached, never deleted).","type":"boolean"},"assets":{"description":"Optional bundle of files shipped with the app in one deploy: images, fonts, audio/video, data. Each asset either carries its bytes inline as `content_base64` or references an already-uploaded attachment by `attachment_id`; the reference form suits real images and media, where the file is uploaded once via `attachments fetch` or presign and then bound here, with no base64 in the deploy body. Each asset is validated + stored app-scoped exactly like a normal attachment (byte-sniff, allowlist, size cap, quota, scan) and served at its `path` on the app's own origin, so the page references it by a stable same-origin path (``, `