Homespun

Official20 tools

by homespunapps · TypeScript

Deploy a multi-user web app from your agent: hosting, auth, database, and permissions.

Model Context Protocol (MCP) Server: dev.homespun/homespun

The MCP server dev.homespun/homespun provides an interface for an agent to deploy a multi-user web application. It focuses on the deployment workflow that includes hosting, authentication, database setup, and permissions configuration.

🛠️ Key Features

Deploy multi-user web applications via an agent
Includes hosting configuration
Includes authentication setup
Includes database provisioning
Supports permissions configuration

🚀 Use Cases

Agent-driven deployment of multi-user web apps
End-to-end setup of hosting + auth + database + permissions for new environments

⚡ Developer Benefits

Consolidates common deployment concerns (hosting, auth, database, permissions) under one agent deployment description
Aligns deployment steps with multi-user application requirements

⚠️ Limitations

Server documentation excerpt provided does not specify available tools, parameters, or supported deployment targets beyond hosting, auth, database, and permissions.

Topics

ai-agentsclaudeclimcpmcp-servertypescripthomespun

Captured live from the server via tools/list.

deploy_app

Deploy a v2 app: an HTML document + a capability manifest, hosted at its own URL. The manifest has eight extension keys: 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; declare update:["creator"] on any collection whose rows belong to one person, or every caller admitted by write can overwrite every row); 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). Pass EITHER no `app_id` (create, mints a slug + URL) OR `app_id` (redeploy an existing app with new content). Supply the HTML as INLINE `html` OR as `html_path` (an absolute path read on the MCP-SERVER host, which is the relay for a hosted connector or your CLI host for a locally-run one, NOT the remote agent's machine; use it to avoid retransmitting a large HTML file every deploy, but only a locally-run connector can read it, and if both are given inline `html` wins). Pass `dry_run:true` (alias `check`) to VALIDATE ONLY: it runs the full manifest + asset-shape validation, the redeploy compat gate, and the schedule-timezone advisory, then returns { ok, warnings, compat?, breaks? } WITHOUT creating a version or mutating anything. A redeploy that NARROWS the manifest (drops a collection, tightens a schema, revokes a role) is refused with manifest_incompatible_redeploy unless force:true; a narrowed collection is then detached, never deleted. Ship images/fonts/audio/video/data FILES with the app in the SAME call via `assets[]`: each is validated + 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 (`<img src="frames/000.jpg">`, `<video src="media/clip.mp4">`), media and font paths support HTTP Range for seeking. A redeploy's assets replace the previous version's set. BEFORE authoring: call get_skill for the manifest grammar. Returns { app_id, slug, url, version, visibility, created } (create) or { app_id, version, compat, breaks? } (redeploy).

Parameters10

app_id	string	optional	Omit to CREATE a new app; pass an existing app's id to REDEPLOY it (a new version, compat-gated unless force:true).
html	string	optional	The app's UI as a complete HTML document (single file, up to the relay's size cap), sent INLINE. Provide EITHER this or `html_path`. Inline is required for a hosted/remote connector that has no filesystem. If both are given, inline `html` wins.
html_path	string	optional	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 your CLI host for a locally-run one), NOT on the remote agent's machine. Alternative to inline `html` that avoids retransmitting a large HTML file on every deploy. Only works when the file is local to the MCP server, so it helps a locally-run connector, not a hosted/remote one (where the path will not exist and you get a clean error, so pass inline `html` there). If both `html` and `html_path` are given, inline `html` wins.
dry_run	boolean	optional	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 narrowing redeploy reports the compat break instead of applying it. `check` is an accepted alias.
check	boolean	optional	Alias for `dry_run`.
manifest	object	required	The x-homespun-manifest capability document (a JSON object). Eight extension keys: 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). Call get_skill for the full grammar before authoring one from scratch.
visibility	string	optional	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`.
slug	string	optional	CREATE only. Accepted with visibility private or public, including the private default; rejected with explicit visibility 'link', where the slug is always server-generated.
force	boolean	optional	REDEPLOY only. Bypass the compat gate on a narrowing manifest change (a removed/narrowed collection is detached, never deleted).
assets	array	optional	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` (prefer the reference form for real images/media: upload once via `attachments fetch` or presign, then bind it 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 (`<img src="frames/000.jpg">`, `<video src="media/intro.mp4">`; media/font paths support HTTP Range). The whole deploy is rejected atomically if any asset fails validation. A redeploy's assets REPLACE the previous version's set. Bounded by the relay's per-deploy asset-count cap; total bytes by the per-app blob quota.

Raw 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, up to the relay's size cap), sent INLINE. Provide EITHER this or `html_path`. Inline is required for a hosted/remote connector that has no filesystem. If both are given, inline `html` wins.",
      "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 your CLI host for a locally-run one), NOT on the remote agent's machine. Alternative to inline `html` that avoids retransmitting a large HTML file on every deploy. Only works when the file is local to the MCP server, so it helps a locally-run connector, not a hosted/remote one (where the path will not exist and you get a clean error, so pass inline `html` 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 narrowing redeploy reports the compat break instead of applying it. `check` is an accepted alias.",
      "type": "boolean"
    },
    "check": {
      "description": "Alias for `dry_run`.",
      "type": "boolean"
    },
    "manifest": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "The x-homespun-manifest capability document (a JSON object). Eight extension keys: 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). Call get_skill for the full grammar before authoring one from scratch."
    },
    "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. Bypass the compat gate on a narrowing manifest change (a removed/narrowed 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` (prefer the reference form for real images/media: upload once via `attachments fetch` or presign, then bind it 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 (`<img src=\"frames/000.jpg\">`, `<video src=\"media/intro.mp4\">`; media/font paths support HTTP Range). The whole deploy is rejected atomically if any asset fails validation. A redeploy's assets REPLACE the previous version's set. Bounded by the relay's per-deploy asset-count cap; total bytes by the per-app blob quota.",
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "path": {
                "type": "string",
                "description": "App-relative, same-origin reference the HTML uses, e.g. 'frames/000.jpg' or 'media/intro.mp4'. Relative ONLY: no leading '/', no '..' segment, no backslash, charset [A-Za-z0-9._/-], not under a reserved prefix (_hs, b)."
              },
              "content_base64": {
                "type": "string",
                "description": "Standard base64 of the asset's raw bytes."
              },
              "mime": {
                "description": "Advisory content-type. The relay sniffs the REAL type from the bytes and enforces the attachment allowlist; omit it (or set application/octet-stream) for data files like CSV that don't magic-byte-sniff, so they are stored + served as an inert download.",
                "type": "string"
              }
            },
            "required": [
              "path",
              "content_base64"
            ]
          },
          {
            "type": "object",
            "properties": {
              "path": {
                "type": "string",
                "description": "App-relative, same-origin reference the HTML uses (same rules as the inline form)."
              },
              "attachment_id": {
                "type": "string",
                "description": "Id of an ALREADY-uploaded attachment to bind at this path, instead of carrying base64. Use with `attachments fetch` (URL, zero model-context cost) or presign + finalize: the attachment must be owned by YOU, app-scoped to THIS app (upload it with scope=app, app_id=this app), and ready. Skips decode/upload; the deploy just maps path -> attachment_id."
              }
            },
            "required": [
              "path",
              "attachment_id"
            ]
          }
        ]
      }
    }
  },
  "required": [
    "manifest"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_rows

List rows in a v2 app's mutable collection. This also doubles as the POLL for a collection's current state (no streaming in MCP): pass the prior next_cursor as `since` to fetch only newer/changed rows. Returns { rows, next_cursor, has_more }.

Parameters4

app_id	string	required	The app id.
collection	string	required	The collection name declared in the app's manifest.
since	string	optional	Opaque cursor from a previous call's next_cursor. Also the POLL handle: pass it back to fetch only newer/changed rows.
limit	integer	optional	Page size.

Raw 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."
    },
    "since": {
      "description": "Opaque cursor from a previous call's next_cursor. Also the POLL handle: pass it back to fetch only newer/changed rows.",
      "type": "string"
    },
    "limit": {
      "description": "Page size.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 1000
    }
  },
  "required": [
    "app_id",
    "collection"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_row

Fetch a single row by its key from a v2 app collection (a dedicated relay route — not a client-side scan). Returns { row } or an isError row_not_found.

Parameters3

app_id	string	required	The app id.
collection	string	required	The collection name.
key	string	required	The key of the row to fetch.

Raw 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 fetch."
    }
  },
  "required": [
    "app_id",
    "collection",
    "key"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

upsert_row

Create a row in a v2 app's collection, or return the existing row if `key` is already present (deduped:true). This is the ONLY create-shaped verb for app rows (no separate strict create). Omit `key` to add a new row (server-generates one); pass `key` to ensure a row exists at that key. The collection must be declared in the app's manifest with 'agent' in its `write` list, the list that gates creates. Returns { row, deduped? }.

Parameters4

app_id	string	required	The app id.
collection	string	required	The collection name.
key	string	optional	Optional stable key. Reusing an existing key returns the existing row (deduped:true).
data	any	required	The row body - any JSON value valid against the collection's row schema (an object, or any JSON value for a schemaless collection).

Raw schema

{
  "type": "object",
  "properties": {
    "app_id": {
      "type": "string",
      "minLength": 1,
      "description": "The app id."
    },
    "collection": {
      "type": "string",
      "minLength": 1,
      "description": "The collection name."
    },
    "key": {
      "description": "Optional stable key. Reusing an existing key returns the existing row (deduped:true).",
      "type": "string"
    },
    "data": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "The row body - any JSON value valid against the collection's row schema (an object, or any JSON value for a schemaless collection)."
    }
  },
  "required": [
    "app_id",
    "collection",
    "data"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

update_row

Update an existing row in a v2 app's collection (replaces its data). Gated by the collection's `update` role list when it declares one, and by its `write` list otherwise, so a collection that scopes updates to the row's `creator` refuses your edit on someone else's row. Pass if_match with the row's current version for an optimistic-locked update: on a version mismatch the relay returns the current row so you can retry. Returns { row }.

Parameters5

app_id	string	required	The app id.
collection	string	required	The collection name.
key	string	required	The key of the row to update.
data	any	required	The new row body (replaces the row's data) - any JSON value valid against the collection's row schema.
if_match	integer	optional	Optional optimistic-lock version. On mismatch the update is rejected with the current row in details.current.

Raw 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 update."
    },
    "data": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "The new row body (replaces the row's data) - any JSON value valid against the collection's row schema."
    },
    "if_match": {
      "description": "Optional optimistic-lock version. On mismatch the update is rejected with the current row in details.current.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "app_id",
    "collection",
    "key",
    "data"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

delete_row

Soft-delete a row from a v2 app's collection. A watcher sees the deletion live (op:delete on the change feed). Pass if_match for an optimistic-locked delete. Returns { deleted: true }.

Parameters4

app_id	string	required	The app id.
collection	string	required	The collection name.
key	string	required	The key of the row to delete.
if_match	integer	optional	Optional optimistic-lock version.

Raw 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#"
}

get_feed_events

Poll a v2 app's change feed for what happened (row creates/updates/deletes, from any writer — agent or human). This is the long-poll analogue of `homespun apps watch` — there is no streaming in MCP. Poll loop: call with no `since` first; process the returned entries; remember cursor; call again passing it as `since` to get only newer entries. To WAIT for activity, pass wait (~25) so the relay holds the request open until an entry arrives or it times out. A `since` older than the retention floor returns resync_required — re-list the collection(s) with list_rows instead. Returns { entries, cursor, truncated }.

Parameters4

app_id	string	required	The app id.
since	integer	optional	Opaque numeric cursor from a previous call's cursor. Omit (or 0) to read from the beginning.
limit	integer	optional	Max entries per page (capped server-side by FEED_PAGE_MAX).
wait	integer	optional	Optional long-poll: how long the relay holds the request open waiting for a new entry (0-30s). Use ~25 when waiting for activity, then call again with the same cursor.

Raw schema

{
  "type": "object",
  "properties": {
    "app_id": {
      "type": "string",
      "minLength": 1,
      "description": "The app id."
    },
    "since": {
      "description": "Opaque numeric cursor from a previous call's cursor. Omit (or 0) to read from the beginning.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Max entries per page (capped server-side by FEED_PAGE_MAX).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "wait": {
      "description": "Optional long-poll: how long the relay holds the request open waiting for a new entry (0-30s). Use ~25 when waiting for activity, then call again with the same cursor.",
      "type": "integer",
      "minimum": 0,
      "maximum": 30
    }
  },
  "required": [
    "app_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

apps

Manage v2 app lifecycle (deploy_app creates/redeploys; this tool covers the rest). ONE tool with an `action` enum: list (YOUR owning human's apps) | show (full detail incl. manifest, timezone, has_share_token) | update (visibility and/or timezone - slug is immutable; switching TO 'link' returns a share_url once) | share_link_rotate (rotate a 'link' app's share token, returning a new share_url and revoking the old link; also generates one if the app has none) | delete (soft-delete, idempotent) | wake (a dormant app; a no-op reporting the actual status otherwise) | domain_set (bind ONE custom domain; returns the DNS records the domain owner must publish) | domain_status (the domain record, live-refreshed against Cloudflare when enabled; inspect last_error when it is not activating) | domain_remove (unbind the domain, idempotent).

Parameters9

action	string	required	list: YOUR owning human's apps. show/update/delete/wake: act on one app (app_id). 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. domain_set/domain_status/domain_remove: manage the app's ONE custom domain (app_id; domain_set also needs domain).
app_id	string	optional	Required for show/update/share_link_rotate/delete/wake/domain_set/domain_status/domain_remove.
status	string	optional	list only. Default: active.
limit	integer	optional	list only. Page size.
cursor	string	optional	list only. Opaque cursor from a previous next_cursor.
slug	string	optional	list only. Exact-match slug filter.
visibility	string	optional	update only. The new visibility (slug is immutable).
timezone	string	optional	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.
domain	string	optional	domain_set only. 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.

Raw schema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "list",
        "show",
        "update",
        "share_link_rotate",
        "delete",
        "wake",
        "domain_set",
        "domain_status",
        "domain_remove"
      ],
      "description": "list: YOUR owning human's apps. show/update/delete/wake: act on one app (app_id). 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. domain_set/domain_status/domain_remove: manage the app's ONE custom domain (app_id; domain_set also needs domain)."
    },
    "app_id": {
      "description": "Required for show/update/share_link_rotate/delete/wake/domain_set/domain_status/domain_remove.",
      "type": "string"
    },
    "status": {
      "description": "list only. Default: active.",
      "type": "string",
      "enum": [
        "active",
        "dormant",
        "archived",
        "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 only. 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.",
      "type": "string"
    }
  },
  "required": [
    "action"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

members

Manage a v2 app's membership (auth spec §6) — who besides the app's owner can sign in to a private app / write to member-scoped collections. ONE tool with an `action` enum: add (invite-or-attach a member by email — attaches immediately if the email already has a Human, otherwise the relay emails a magic-link invite) | list (the app's owner + members) | set_role (change an existing member's declared custom role in place, or null to clear it — does NOT revoke their sessions, so use this rather than remove-then-add to re-role someone) | remove (idempotent; also revokes the human's live sessions on this app — the app owner cannot be removed) | roles (the derived roles summary: per declared role and collection, the EFFECTIVE access a holder actually has, reported separately for signed-in members and for grant-link holders since their role floors differ, plus member and active-grant-link counts).

Parameters6

action	string	required	add: invite-or-attach a member by email (app_id+email; optional custom_role). list: the app's owner + members (app_id). set_role: change an existing member's custom role in place without signing them out (app_id+human_id+custom_role, null to clear). remove: drop a member (app_id+human_id). roles: the app's declared roles with, per collection, the EFFECTIVE access a holder has (separately for members and grant-link holders, whose role floors differ) plus how many members and live grant links hold each role (app_id).
app_id	string	required	The app id.
email	string	optional	add only. The email to invite/attach. If a Human already exists for it, the member row is attached immediately; otherwise the relay emails a magic-link invite.
role	string	optional	add only. Defaults to 'member' server-side — no other role is assignable via this API (ownership transfer is not available here).
custom_role	any	optional	add (optional) and set_role (required). A DECLARED custom role (an x-homespun-manifest.roles key) attached to the member ALONGSIDE their base member powers. A built-in/reserved role or an undeclared role is rejected. Omit on add for an ordinary member; pass null on set_role to clear the role back to a plain member.
human_id	string	optional	remove and set_role. The Human id to target — see list's `humanId` field. The app owner can be neither removed nor re-roled.

Raw schema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "add",
        "list",
        "set_role",
        "remove",
        "roles"
      ],
      "description": "add: invite-or-attach a member by email (app_id+email; optional custom_role). list: the app's owner + members (app_id). set_role: change an existing member's custom role in place without signing them out (app_id+human_id+custom_role, null to clear). remove: drop a member (app_id+human_id). roles: the app's declared roles with, per collection, the EFFECTIVE access a holder has (separately for members and grant-link holders, whose role floors differ) plus how many members and live grant links hold each role (app_id)."
    },
    "app_id": {
      "type": "string",
      "minLength": 1,
      "description": "The app id."
    },
    "email": {
      "description": "add only. The email to invite/attach. If a Human already exists for it, the member row is attached immediately; otherwise the relay emails a magic-link invite.",
      "type": "string"
    },
    "role": {
      "description": "add only. Defaults to 'member' server-side — no other role is assignable via this API (ownership transfer is not available here).",
      "type": "string",
      "enum": [
        "member"
      ]
    },
    "custom_role": {
      "description": "add (optional) and set_role (required). A DECLARED custom role (an x-homespun-manifest.roles key) attached to the member ALONGSIDE their base member powers. A built-in/reserved role or an undeclared role is rejected. Omit on add for an ordinary member; pass null on set_role to clear the role back to a plain member.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "human_id": {
      "description": "remove and set_role. The Human id to target — see list's `humanId` field. The app owner can be neither removed nor re-roled.",
      "type": "string"
    }
  },
  "required": [
    "action",
    "app_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

grants

Manage a v2 app's grant links (M5). A grant link is a capability URL that confers a DECLARED custom role (x-homespun-manifest.roles) on a stable, per-holder anonymous identity, so the holder's own rows are isolated by author/:own scoping. A grant NEVER escalates to owner/member/agent. ONE tool with an `action` enum: mint (create a link; returns a `grant_url` carrying the token in its #g= fragment, shown ONCE, never recoverable) | list (the app's links, never any token) | revoke (idempotent). mode once = one-time (first-browser-claims), multi = shared (capped by max_uses within expiry). An optional pin (pin_row_key OR pin_where) NARROWS the holder to specific rows, never widens. Note: a write-only grant pinned to a single row key can still read that row's existing data back via create dedup, so a 'write-only to slot X' grant exposes slot X's current contents to the holder.

Parameters10

action	string	required	mint: create a grant link carrying a declared custom role (app_id+role). list: the app's grant links (app_id). revoke: revoke one link (app_id+grant_id).
app_id	string	required	The app id.
role	string	optional	mint only. A DECLARED custom role for the app (an x-homespun-manifest.roles key). A built-in role (owner/member/agent/anyone) is rejected: a grant can never escalate.
mode	string	optional	mint only. once: one-time link, claimed by the first browser that opens it (a real per-person link; later opens by others are inert). multi (default): a shared link, capped by max_uses within expiry.
max_uses	integer	optional	mint only (multi mode). Cap total claims; omit for unlimited within expiry. Ignored for once (forced to 1).
label	string	optional	mint only. Optional owner label shown in the grant list.
ttl_seconds	integer	optional	mint only. Grant lifetime in seconds; defaults to the server default (30 days) and is clamped to the server max.
pin_row_key	string	optional	mint only. Optional narrowing pin to a single row key. NARROWS within the role (never widens). Mutually exclusive with pin_where.
pin_where	array	optional	mint only. Optional narrowing pin as Wave C2 where conditions ({field, op, value}[]). NARROWS within the role (never widens). Mutually exclusive with pin_row_key.
grant_id	string	optional	revoke only. The grant link id (see list's `id` field).

Raw schema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "mint",
        "list",
        "revoke"
      ],
      "description": "mint: create a grant link carrying a declared custom role (app_id+role). list: the app's grant links (app_id). revoke: revoke one link (app_id+grant_id)."
    },
    "app_id": {
      "type": "string",
      "minLength": 1,
      "description": "The app id."
    },
    "role": {
      "description": "mint only. A DECLARED custom role for the app (an x-homespun-manifest.roles key). A built-in role (owner/member/agent/anyone) is rejected: a grant can never escalate.",
      "type": "string"
    },
    "mode": {
      "description": "mint only. once: one-time link, claimed by the first browser that opens it (a real per-person link; later opens by others are inert). multi (default): a shared link, capped by max_uses within expiry.",
      "type": "string",
      "enum": [
        "once",
        "multi"
      ]
    },
    "max_uses": {
      "description": "mint only (multi mode). Cap total claims; omit for unlimited within expiry. Ignored for once (forced to 1).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "label": {
      "description": "mint only. Optional owner label shown in the grant list.",
      "type": "string"
    },
    "ttl_seconds": {
      "description": "mint only. Grant lifetime in seconds; defaults to the server default (30 days) and is clamped to the server max.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "pin_row_key": {
      "description": "mint only. Optional narrowing pin to a single row key. NARROWS within the role (never widens). Mutually exclusive with pin_where.",
      "type": "string"
    },
    "pin_where": {
      "description": "mint only. Optional narrowing pin as Wave C2 where conditions ({field, op, value}[]). NARROWS within the role (never widens). Mutually exclusive with pin_row_key.",
      "type": "array",
      "items": {}
    },
    "grant_id": {
      "description": "revoke only. The grant link id (see list's `id` field).",
      "type": "string"
    }
  },
  "required": [
    "action",
    "app_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

ingest

Manage a v2 app's inbound catch-hooks (inbound-webhooks). A catch-hook lets an EXTERNAL system (Stripe, Zapier, Make, Home Assistant, an email router) POST JSON to a secret URL that writes into a declared collection, so the app receives data even with no agent online. Hooks are DECLARED IN THE MANIFEST (x-homespun-manifest.ingest) and materialized at deploy, so this tool has no create/delete: use it to READ BACK the URL, rotate a leaked one, and manage the opt-in signing secret. ONE tool with an `action` enum: list (the app's hooks, each with its full secret URL, current rule collection/mode/wake/handshake, per-status delivery counts, and signing-secret state) | rotate (mint a fresh URL secret for one hook by name and return its NEW url once; the old url stops working immediately, no redeploy needed) | set_signing_secret (provision/rotate a hook's signing secret, a DIFFERENT secret from the URL: what a provider HMACs the body with; omit `secret` to mint one returned ONCE, or pass `secret` to store a provider value verbatim, never echoed) | clear_signing_secret (remove it). Signature verification ships DARK for now: nothing verifies a signature yet. After deploying a manifest that declares a hook, run list and tell the owner the exact url to paste into the external system.

Parameters5

action	string	required	list: the app's inbound catch-hooks, each with its full secret URL, current rule (collection/mode/wake/handshake), and per-status delivery counts (app_id). rotate: mint a fresh URL secret for one hook and return its new URL once, invalidating the old URL immediately (app_id+name). set_signing_secret: provision or rotate a hook's OPT-IN signing secret, distinct from the URL secret (it is what a provider HMACs the body with); omit `secret` to mint one (returned ONCE) or pass `secret` to store a provider-generated value verbatim (never echoed) (app_id+name). clear_signing_secret: remove a hook's signing secret (app_id+name).
app_id	string	required	The app id.
name	string	optional	rotate / set_signing_secret / clear_signing_secret. The manifest ingest hook name (an x-homespun-manifest.ingest[].name). See list's `name` field.
secret	string	optional	set_signing_secret only. A provider-generated signing secret to store verbatim (the Stripe path). Omit to have the relay mint one (the GitHub path), returned ONCE in the response.
grace_seconds	number	optional	set_signing_secret only. On a rotation, how long the previous secret stays valid so deliveries verify while you update the provider (default 3600, max 86400).

Raw schema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "list",
        "rotate",
        "set_signing_secret",
        "clear_signing_secret"
      ],
      "description": "list: the app's inbound catch-hooks, each with its full secret URL, current rule (collection/mode/wake/handshake), and per-status delivery counts (app_id). rotate: mint a fresh URL secret for one hook and return its new URL once, invalidating the old URL immediately (app_id+name). set_signing_secret: provision or rotate a hook's OPT-IN signing secret, distinct from the URL secret (it is what a provider HMACs the body with); omit `secret` to mint one (returned ONCE) or pass `secret` to store a provider-generated value verbatim (never echoed) (app_id+name). clear_signing_secret: remove a hook's signing secret (app_id+name)."
    },
    "app_id": {
      "type": "string",
      "minLength": 1,
      "description": "The app id."
    },
    "name": {
      "description": "rotate / set_signing_secret / clear_signing_secret. The manifest ingest hook name (an x-homespun-manifest.ingest[].name). See list's `name` field.",
      "type": "string"
    },
    "secret": {
      "description": "set_signing_secret only. A provider-generated signing secret to store verbatim (the Stripe path). Omit to have the relay mint one (the GitHub path), returned ONCE in the response.",
      "type": "string"
    },
    "grace_seconds": {
      "description": "set_signing_secret only. On a rotation, how long the previous secret stays valid so deliveries verify while you update the provider (default 3600, max 86400).",
      "type": "number"
    }
  },
  "required": [
    "action",
    "app_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

attachments

Binary attachments (images, PDFs, audio, video) referenced from event payloads / input_data via `format: homespun-attachment-id`. ONE tool with an `action` enum: upload | fetch | presign | finalize | download | show | list | delete | mint_token | revoke_token | list_tokens. TOKEN COST, READ FIRST: an inline `upload` with `content_base64` carries the bytes in the tool-call arguments, so they enter the MODEL CONTEXT and cost tokens PROPORTIONAL TO FILE SIZE (a few-hundred-KB image is already very costly, worse on every retry). For ANY real image or media (anything beyond a tiny icon) use a ZERO-CONTEXT path instead: `fetch` when you have a URL (the relay downloads it server-side, you send only the URL string), or presign + finalize when the client can PUT the raw bytes out-of-band. fetch: { source_url (https), scope } — the relay downloads the URL itself behind an SSRF guard (https only, no private/loopback/metadata hosts, DNS pinned, redirects refused, size-capped, timed out) and runs the same byte-sniff + allowlist + size + quota + scan checks as any upload; works on any storage backend. upload (inline) takes EITHER `content_base64` (base64 bytes, no filesystem; last-resort for small assets or clients with neither a URL nor an out-of-band PUT) OR `file_path` (ABSOLUTE path read on the RELAY host, only usable when the file is local to the relay). presign + finalize (token-free, for images/video/big audio): (1) presign with { mime, size, sha256, scope } returns { put_url, attachment_id }; (2) YOU PUT the raw bytes to put_url over plain HTTP out-of-band; (3) finalize with the attachment_id. At finalize the relay re-reads the stored bytes, BYTE-SNIFFS the real type, and enforces the same allowlist + size + sha256 + quota + scan checks as any upload, so a presign that lies about its mime is caught and never served inline. The presigned path requires the Azure storage backend; a filesystem self-host returns a clear not-supported error (use fetch or inline upload there). download writes to an ABSOLUTE out_path (or returns base64). Scope an upload to agent (default, reusable) or app. mint_token returns a /b/<token> capability URL (ONCE) a browser can GET without your API key.

Parameters17

action	string	required	Binary attachment operations. For ANY real image or media (anything beyond a tiny icon) PREFER a ZERO-CONTEXT path so the bytes never enter the model context and cost NO tokens: `fetch` when you have a URL (the relay downloads it server-side; you send only the URL string), or presign + finalize when the client can PUT the raw bytes out-of-band. upload with `content_base64` sends the bytes INLINE in the tool-call arguments, loading them into the model context at a token cost PROPORTIONAL TO FILE SIZE (even a few-hundred-KB image is very costly, worse on every retry); use it only as a last-resort fallback for small assets or clients that have neither a URL nor an out-of-band PUT. fetch: pass { source_url, scope } and the relay fetches the bytes itself (https only, SSRF-guarded) and runs the same sniff/allowlist/size/quota/scan checks as any upload. upload: `content_base64` (base64 bytes, no filesystem) or `file_path` (absolute, read on the RELAY host); scope agent\|app. presign + finalize: (1) presign with { mime, size, sha256, scope }, (2) PUT the bytes to put_url out-of-band, (3) finalize confirms it (re-sniffs + re-checks the bytes). download: fetch bytes by attachment_id to out_path (absolute) or return base64. show: metadata only. list: the agent's attachments. delete: soft-delete. mint_token: mint a /b/<token> capability URL (returned ONCE). revoke_token / list_tokens: manage those tokens.
size	integer	optional	presign: the exact byte length you will PUT. Committed at presign and re-verified against the uploaded bytes at finalize.
sha256	string	optional	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.
attachment_id	string	optional	Attachment id. Required for download/show/delete/mint_token/revoke_token/list_tokens.
file_path	string	optional	upload: ABSOLUTE path to a file read on the SERVER host running this MCP connector (the relay), NOT your machine. Only works when the file is local to the relay (e.g. a locally-run CLI). For a hosted or remote agent, use `content_base64` instead.
source_url	string	optional	fetch: an https URL the RELAY downloads server-side, so the bytes NEVER enter the model context (zero token cost). SSRF-guarded: https only, no private/loopback/link-local/metadata hosts, DNS pinned, redirects refused, size-capped, timed out. The downloaded bytes run the same byte-sniff/allowlist/size/quota/scan checks as any upload. Prefer this (or presign+finalize) over `content_base64` for real images/media.
content_base64	string	optional	upload: the file bytes as base64, sent INLINE with no filesystem access. WARNING: 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 very costly, and it compounds on every retry). PREFER presign + finalize for any real image or media whenever the client can do an out-of-band HTTP PUT; reserve `content_base64` for small assets (a tiny icon) or 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/quota checks as a file upload.
scope	string	optional	upload scope (default agent).
app_id	string	optional	Required when scope=app.
filename	string	optional	upload: display filename (defaults to the file's basename).
mime	string	optional	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).
out_path	string	optional	download: ABSOLUTE path to write the bytes to. If omitted, the bytes are returned base64-encoded in the result.
cursor	string	optional	list pagination cursor.
limit	integer	optional	list page size (1..100).
ttl_seconds	integer	optional	mint_token: per-token TTL (clamped by scope default).
once	boolean	optional	mint_token: token self-deletes on first GET.
token_id	string	optional	revoke_token: the token id to revoke.

Raw 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. For ANY real image or media (anything beyond a tiny icon) PREFER a ZERO-CONTEXT path so the bytes never enter the model context and cost NO tokens: `fetch` when you have a URL (the relay downloads it server-side; you send only the URL string), or presign + finalize when the client can PUT the raw bytes out-of-band. upload with `content_base64` sends the bytes INLINE in the tool-call arguments, loading them into the model context at a token cost PROPORTIONAL TO FILE SIZE (even a few-hundred-KB image is very costly, worse on every retry); use it only as a last-resort fallback for small assets or clients that have neither a URL nor an out-of-band PUT. fetch: pass { source_url, scope } and the relay fetches the bytes itself (https only, SSRF-guarded) and runs the same sniff/allowlist/size/quota/scan checks as any upload. upload: `content_base64` (base64 bytes, no filesystem) or `file_path` (absolute, read on the RELAY host); scope agent|app. presign + finalize: (1) presign with { mime, size, sha256, scope }, (2) PUT the bytes to put_url out-of-band, (3) finalize confirms it (re-sniffs + re-checks the bytes). download: fetch bytes by attachment_id to out_path (absolute) or return base64. show: metadata only. list: the agent's attachments. delete: soft-delete. mint_token: mint a /b/<token> capability URL (returned ONCE). revoke_token / 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 your machine. Only works when the file is local to the relay (e.g. a locally-run CLI). For a hosted or remote agent, use `content_base64` instead.",
      "type": "string"
    },
    "source_url": {
      "description": "fetch: an https URL the RELAY downloads server-side, so the bytes NEVER enter the model context (zero token cost). SSRF-guarded: https only, no private/loopback/link-local/metadata hosts, DNS pinned, redirects refused, size-capped, timed out. The downloaded bytes run the same byte-sniff/allowlist/size/quota/scan checks as any upload. Prefer this (or presign+finalize) over `content_base64` for real images/media.",
      "type": "string"
    },
    "content_base64": {
      "description": "upload: the file bytes as base64, sent INLINE with no filesystem access. WARNING: 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 very costly, and it compounds on every retry). PREFER presign + finalize for any real image or media whenever the client can do an out-of-band HTTP PUT; reserve `content_base64` for small assets (a tiny icon) or 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/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#"
}

taste

Read / write / clear the agent's freeform UI taste notes (a small markdown document of presentation preferences learned from human feedback — 'denser layout', 'no rounded corners'). ONE tool with an `action` enum: get | set | clear. Call `get` BEFORE generating an app so prior feedback shapes the output; `set` does a whole-document replace (not append). Keep entries about UI/presentation only.

Parameters2

action	string	required	The agent's freeform UI taste notes (markdown) — presentation preferences learned from human feedback. get: read them before generating an app. set: whole-document replace (taste, non-empty). clear: delete them.
taste	string	optional	The full markdown notes (required for set; whole-document replace, not append).

Raw schema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "get",
        "set",
        "clear"
      ],
      "description": "The agent's freeform UI taste notes (markdown) — presentation preferences learned from human feedback. get: read them before generating an app. set: whole-document replace (taste, non-empty). clear: delete them."
    },
    "taste": {
      "description": "The full markdown notes (required for set; whole-document replace, not append).",
      "type": "string"
    }
  },
  "required": [
    "action"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

key

Inspect, mint, or revoke the calling agent's API key. ONE tool with an `action` enum: list (key info: agent_id, key_prefix, timestamps) | mint (mint a NEW sibling API key for YOUR OWN agent identity, same scope/ownership, and return its raw value ONCE, the way an MCP-driven agent bootstraps a CLI/child-process credential; the raw key is never retrievable again, the sibling appears in a `list` made WITH it, and the owner can revoke it) | revoke (self-destruct the agent's OWN key; it stops working immediately and is irreversible, so pass confirm:true). The relay derives identity from the caller's token, so every action acts only on the caller's own agent, and mint can never target another agent's id.

Parameters2

action	string	required	The calling agent's API key. list: key info (agent_id, key_prefix, timestamps). mint: mint a NEW sibling API key for YOUR OWN agent identity (same scope/ownership) and return its raw value ONCE, so use it to hand a CLI or child process a working credential; the sibling is a distinct key that shows up in a subsequent `list` made WITH it, the owner can revoke it, and the raw value is never retrievable again. mint always acts on the calling agent, never another agent's id. revoke: self-destruct the agent's OWN key, which stops working immediately and is irreversible (requires confirm:true).
confirm	boolean	optional	Required (true) for revoke.

Raw schema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "list",
        "revoke",
        "mint"
      ],
      "description": "The calling agent's API key. list: key info (agent_id, key_prefix, timestamps). mint: mint a NEW sibling API key for YOUR OWN agent identity (same scope/ownership) and return its raw value ONCE, so use it to hand a CLI or child process a working credential; the sibling is a distinct key that shows up in a subsequent `list` made WITH it, the owner can revoke it, and the raw value is never retrievable again. mint always acts on the calling agent, never another agent's id. revoke: self-destruct the agent's OWN key, which stops working immediately and is irreversible (requires confirm:true)."
    },
    "confirm": {
      "description": "Required (true) for revoke.",
      "type": "boolean"
    }
  },
  "required": [
    "action"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

feedback

Send or list feedback to the relay operator. ONE tool with an `action` enum: create (a bug|feature|note with a message, optional app_id) | list (the agent's own submissions, newest first, paginated by before).

Parameters6

action	string	required	Feedback to the relay operator. create: submit a bug\|feature\|note with a message (optional app_id). list: the agent's own submissions, newest first.
type	string	optional	Feedback category (required for create).
message	string	optional	Message body (required for create).
app_id	string	optional	Optional app this feedback relates to (create).
limit	integer	optional	list page size (default 50, max 100).
before	string	optional	list cursor from a prior page's next_before.

Raw schema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "create",
        "list"
      ],
      "description": "Feedback to the relay operator. create: submit a bug|feature|note with a message (optional app_id). list: the agent's own submissions, newest first."
    },
    "type": {
      "description": "Feedback category (required for create).",
      "type": "string",
      "enum": [
        "bug",
        "feature",
        "note"
      ]
    },
    "message": {
      "description": "Message body (required for create).",
      "type": "string"
    },
    "app_id": {
      "description": "Optional app this feedback relates to (create).",
      "type": "string"
    },
    "limit": {
      "description": "list page size (default 50, max 100).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    },
    "before": {
      "description": "list cursor from a prior page's next_before.",
      "type": "string"
    }
  },
  "required": [
    "action"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

agent

Agent identity + binding. ONE tool with an `action` enum: whoami (the resolved relay URL, active profile, whether a key is configured — no network, no secrets) | claim (bind this agent to a human via a one-shot claim code from their Settings UI; one-way) | logout (clear the locally-saved key/profile; does NOT revoke it on the relay — use the `key` tool's revoke for that).

Parameters2

action	string	required	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: clear the locally-saved key/profile (does NOT revoke it on the relay — use the key tool's revoke for that).
code	string	optional	The one-shot claim code (required for claim).

Raw 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: clear the locally-saved key/profile (does NOT revoke it on the relay — use the key tool's revoke for that)."
    },
    "code": {
      "description": "The one-shot claim code (required for claim).",
      "type": "string"
    }
  },
  "required": [
    "action"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

community

Publish an app you own as a COMMUNITY TEMPLATE, install a template into your own account, and (relay operators only) review submissions. ONE tool with an `action` enum: publish | get_config_contract | install | list_pending | get_submission | approve | reject | set_trust_level. publish captures your live app (html + manifest + the seed rows of its seedOnInstall collections + listing metadata) into a PENDING template - installable by the returned direct link but NOT listed in the public gallery until an operator approves it; you must have a verified email and at most a few pending submissions at once. PRIVACY: an approved template's content AND its captured seed rows become PUBLIC to every platform user, so never publish an app whose seedOnInstall collections hold real personal data - seed data must be example-only. Pass attest_example_only:true to attest you checked this. Optionally give the template a per-publisher `slug` (namespaced id <your-handle>/<slug>) and a semver `version` (default 1.0.0): a republish under the same slug must bump the version. get_config_contract reads what a template needs at install (its settings collection + ordered config/upload steps) by `ref`; install creates a fresh PRIVATE copy of a template for YOUR owning human, passing the answers as `config` (a 'config' value is a string, an 'upload' value is a pre-uploaded attachment id from the attachments tool). The review actions are limited to the relay's configured community reviewers: list_pending (the queue), get_submission (a submission's full content by snapshot_id), approve (list it in the gallery; a re-publish supersedes your app's prior approved version), reject (with a required note that lands in the publisher's app feed).

Parameters21

action	string	required	publish: publish one of YOUR apps as a community template (app_id; optional title/description/category/tags). PRIVACY: 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. Do NOT publish an app whose seedOnInstall collections hold real personal data (names, emails, addresses, messages, anything private): seed data must be example-only. Pass attest_example_only:true to attest you have checked this. 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 (the response's expedited/auto_approved tell you which). get_config_contract: read a template's install-time config contract by `ref` (a namespaced '<handle>/<slug>' 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-upload it with the attachments tool (scope agent) and pass its attachment id. After installing a template with connect_steps, run the `ingest` tool's list action on the new app_id to read its freshly provisioned hook URLs, and wire each into the external service. install: install a template by `ref` for YOU (your owning human becomes the owner). Pass `config` as { stepKey: value } from the contract: a 'config' step's value is a string, an 'upload' step's value is a pre-uploaded attachment id. A required step you omit 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').
ref	string	optional	get_config_contract/install only. The template to read or install: a namespaced '<handle>/<slug>' or a community snapshot id.
config	object	optional	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.
app_id	string	optional	publish only. The id of an app YOU own to publish.
title	string	optional	publish only. Listing title (1 to 80 chars). Defaults to the app's manifest name.
description	string	optional	publish only. Listing blurb (up to 200 chars). Defaults to the manifest description.
long_description	string	optional	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.
category	string	optional	publish only. Optional single-word category (e.g. 'household').
tags	array	optional	publish only. Up to 6 curation tags.
slug	string	optional	publish only. Optional per-publisher slug (lowercase, 3 to 48 chars, hyphens). Gives the template a namespaced id <your-handle>/<slug>; a republish reuses the slug and must bump the version.
version	string	optional	publish only. Semver MAJOR.MINOR.PATCH (default '1.0.0'). A republish under the same slug must be strictly greater than the current version.
changelog_note	string	optional	publish only. A short note recorded in this version's changelog.
setup_steps	array	optional	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.
derived_from_snapshot_id	string	optional	publish only. Optional remix/fork lineage: the snapshot id this template was derived from.
attest_example_only	boolean	optional	publish only. Set true to attest 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 your 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.
snapshot_id	string	optional	Required for get_submission/approve/reject. The submission's snapshot id (from publish's response or list_pending).
note	string	optional	reject only. The required rejection note shown to the publisher (delivered to their app feed).
limit	integer	optional	list_pending only. Page size (1..200).
cursor	string	optional	list_pending only. Opaque cursor from a prior next_cursor.
handle	string	optional	set_trust_level only. The @-handle of the publisher to promote or demote.
trust_level	string	optional	set_trust_level only. 'established' fast-tracks the publisher's future submissions through review; 'new' reverts to full review.

Raw schema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "publish",
        "get_config_contract",
        "install",
        "list_pending",
        "get_submission",
        "approve",
        "reject",
        "set_trust_level"
      ],
      "description": "publish: publish one of YOUR apps as a community template (app_id; optional title/description/category/tags). PRIVACY: 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. Do NOT publish an app whose seedOnInstall collections hold real personal data (names, emails, addresses, messages, anything private): seed data must be example-only. Pass attest_example_only:true to attest you have checked this. 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 (the response's expedited/auto_approved tell you which). get_config_contract: read a template's install-time config contract by `ref` (a namespaced '<handle>/<slug>' 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-upload it with the attachments tool (scope agent) and pass its attachment id. After installing a template with connect_steps, run the `ingest` tool's list action on the new app_id to read its freshly provisioned hook URLs, and wire each into the external service. install: install a template by `ref` for YOU (your owning human becomes the owner). Pass `config` as { stepKey: value } from the contract: a 'config' step's value is a string, an 'upload' step's value is a pre-uploaded attachment id. A required step you omit 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')."
    },
    "ref": {
      "description": "get_config_contract/install only. The template to read or install: a namespaced '<handle>/<slug>' 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 only. The id of an app YOU own to publish.",
      "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 <your-handle>/<slug>; a republish reuses the slug and must bump the version.",
      "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, optional there; publish rejects a name 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. Set true to attest 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 your 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/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#"
}

publisher

Manage YOUR community publisher identity: the @-handle and public profile you present in the template gallery. ONE tool with an `action` enum: claim | get | update. get returns your profile (handle, whether it is claimed yet, tenure, and the rating/template counters). claim sets your handle exactly ONCE (it is permanent afterwards) from a lowercase 3-to-32-char string; a handle that is reserved (platform or role words) or already taken is refused. update changes your public display_name, bio, or url at any time. claim and update require a verified email; an existing publisher may already have a provisional `maker-...` handle (auto-assigned) that claim renames the one allowed time.

Parameters5

action	string	required	get: return YOUR publisher profile (handle, tenure, counters). claim: set your @-handle ONCE (handle arg; lowercase, 3 to 32 chars, permanent after claiming; needs a verified email). update: change your public display_name/bio/url (any of them; needs a verified email).
handle	string	optional	claim only. The lowercase @-handle to claim (^[a-z0-9](?:[a-z0-9-]{1,30}[a-z0-9])$). Permanent once claimed.
display_name	any	optional	update only. Public display name (up to 80 chars); null clears it.
bio	any	optional	update only. Short public bio (up to 500 chars); null clears it.
url	any	optional	update only. Public http(s) URL (up to 200 chars); null clears it.

Raw schema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "claim",
        "get",
        "update"
      ],
      "description": "get: return YOUR publisher profile (handle, tenure, counters). claim: set your @-handle ONCE (handle arg; lowercase, 3 to 32 chars, permanent after claiming; needs a verified email). update: change your public display_name/bio/url (any of them; needs a verified email)."
    },
    "handle": {
      "description": "claim only. The lowercase @-handle to claim (^[a-z0-9](?:[a-z0-9-]{1,30}[a-z0-9])$). Permanent once claimed.",
      "type": "string"
    },
    "display_name": {
      "description": "update only. Public display name (up to 80 chars); null clears it.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "bio": {
      "description": "update only. Short public bio (up to 500 chars); null clears it.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "url": {
      "description": "update only. Public http(s) URL (up to 200 chars); null clears it.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "action"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

review

Rate and review community templates you have USED, respond to reviews of your own templates, and (relay operators only) moderate. ONE tool with an `action` enum: create | respond | report | remove | unhold. create leaves a 1-to-5 star rating plus an optional written body on a template you have installed - identify the template by `template` ("<handle>/<slug>") or by `handle`+`slug`; you need a verified email, and each install yields exactly one review (the aggregate carries across template versions). A body that contains a link or a contact email is AUTO-HELD for a moderator before it appears. respond replies to a review of YOUR OWN template line (review_id + response; null clears it), one editable response per review. report flags a review for the relay's moderators (review_id + reason), deduped per account. remove and unhold are limited to the relay's configured community reviewers: remove takes a review down and adjusts the rating aggregate; unhold publishes a previously auto-held review into the aggregate.

Parameters9

action	string	required	create: leave a star rating (1..5) and optional body on a community template YOU have installed (identify it by `template` "<handle>/<slug>" or by `handle`+`slug`); requires a verified email, and one review per install. A body containing a link or contact email is auto-held for a moderator before it shows. respond: reply to a review of one of YOUR OWN templates (review_id + response; null clears it). report: flag a review for the relay's moderators (review_id + reason; one report per account). remove / unhold are RELAY-OPERATOR-only moderation actions on a review_id: remove takes a review down (adjusting the aggregate), unhold publishes a previously auto-held review.
template	string	optional	create only. The namespaced template id <handle>/<slug> to review.
handle	string	optional	create only. Publisher handle (with `slug`), an alternative to `template`.
slug	string	optional	create only. Per-publisher slug (with `handle`).
stars	integer	optional	create only. Star rating, an integer 1 to 5.
body	string	optional	create only. Optional written review (up to 2000 chars).
review_id	string	optional	Required for respond/report/remove/unhold. The review's id.
response	any	optional	respond only. The publisher's public response (up to 2000 chars); null clears it.
reason	string	optional	report only. Why you are reporting this review (up to 500 chars).

Raw schema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "create",
        "respond",
        "report",
        "remove",
        "unhold"
      ],
      "description": "create: leave a star rating (1..5) and optional body on a community template YOU have installed (identify it by `template` \"<handle>/<slug>\" or by `handle`+`slug`); requires a verified email, and one review per install. A body containing a link or contact email is auto-held for a moderator before it shows. respond: reply to a review of one of YOUR OWN templates (review_id + response; null clears it). report: flag a review for the relay's moderators (review_id + reason; one report per account). remove / unhold are RELAY-OPERATOR-only moderation actions on a review_id: remove takes a review down (adjusting the aggregate), unhold publishes a previously auto-held review."
    },
    "template": {
      "description": "create only. The namespaced template id <handle>/<slug> to review.",
      "type": "string"
    },
    "handle": {
      "description": "create only. Publisher handle (with `slug`), an alternative to `template`.",
      "type": "string"
    },
    "slug": {
      "description": "create only. Per-publisher slug (with `handle`).",
      "type": "string"
    },
    "stars": {
      "description": "create only. Star rating, an integer 1 to 5.",
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "body": {
      "description": "create only. Optional written review (up to 2000 chars).",
      "type": "string"
    },
    "review_id": {
      "description": "Required for respond/report/remove/unhold. The review's id.",
      "type": "string"
    },
    "response": {
      "description": "respond only. The publisher's public response (up to 2000 chars); null clears it.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "reason": {
      "description": "report only. Why you are reporting this review (up to 500 chars).",
      "type": "string"
    }
  },
  "required": [
    "action"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_skill

Fetch the relay's auto-updating SKILL.md (the full Homespun usage guide) — UNAUTHENTICATED, needs no API key. Call this to self-teach the Homespun workflow (events vs records, schema grammars, the poll loop) before driving the other tools. Pass version_only:true to get just the relay's skill version string (to check if a cached copy is stale).

Parameters1

version_only

boolean

optional

If true, return only the relay's current skill version string instead of the full SKILL.md markdown.

Raw schema

{
  "type": "object",
  "properties": {
    "version_only": {
      "description": "If true, return only the relay's current skill version string instead of the full SKILL.md markdown.",
      "type": "boolean"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

packages/mcp/README.md8 KBView on GitHub

@homespunapps/mcp

A thin stdio Model Context Protocol server for Homespun. It lets any MCP client (Claude Desktop, Cursor, Windsurf, Cline, your own host) deploy a real multi-user web app in one call and keep operating its data afterwards: hosting on its own URL, magic-link identity, a shared realtime database with per-role permissions, email notifications and file attachments, all included.

It is a wrapper, not a reimplementation: all relay I/O goes through @homespunapps/core, and config is shared with the homespun CLI (~/.config/homespun/config.json), so the CLI and this server use the same agent identity.

Runtime requirement: Node.js >= 20

The binary is homespun-mcp. It speaks MCP over stdio and is meant to be launched by an MCP host, not run interactively.

Quickstart

No global install needed: point your MCP client at npx @homespunapps/mcp. On first use, if no API key is configured, the server auto-registers a fresh agent against the hosted relay and saves the key to the shared CLI store; nothing else to set up.

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

json

{
  "mcpServers": {
    "homespun": {
      "command": "npx",
      "args": ["-y", "@homespunapps/mcp"]
    }
  }
}

To pin an existing agent key instead of auto-registering, add an env block:

json

{
  "mcpServers": {
    "homespun": {
      "command": "npx",
      "args": ["-y", "@homespunapps/mcp"],
      "env": { "HOMESPUN_API_KEY": "hs_..." }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

json

{
  "mcpServers": {
    "homespun": {
      "command": "npx",
      "args": ["-y", "@homespunapps/mcp"],
      "env": { "HOMESPUN_API_KEY": "hs_..." }
    }
  }
}

Generic MCP host

Any client that takes a command + args + env works the same way:

json

{
  "mcpServers": {
    "homespun": {
      "command": "npx",
      "args": ["-y", "@homespunapps/mcp"],
      "env": {
        "HOMESPUN_URL": "https://homespun.dev",
        "HOMESPUN_API_KEY": "hs_..."
      }
    }
  }
}

If you'd rather install it globally (npm i -g @homespunapps/mcp), use "command": "homespun-mcp" with no args.

Configuration

All environment variables are optional; the defaults target the hosted relay and auto-register on first use.

Variable	Default	Purpose
`HOMESPUN_URL`	`https://homespun.dev`	Relay base URL. Set to point at a different relay.
`HOMESPUN_API_KEY`	(auto-registered)	Agent API key. If unset, the server registers an agent on first use and saves the key to `~/.config/homespun/config.json` (shared with the CLI).
`HOMESPUN_TOKEN`	(none)	Alias for `HOMESPUN_API_KEY` (for hosts that name secrets `*_TOKEN`). `HOMESPUN_API_KEY` wins if both are set.
`HOMESPUN_AGENT_NAME`	`homespun-mcp`	Display name for the auto-registered agent.
`HOMESPUN_REGISTER_SECRET`	(none)	Registration secret, only for relays running `REGISTRATION_MODE=secret`.

Config precedence mirrors the CLI: env vars win over the saved profile, which falls back to the default relay URL.

Tools

This server has full parity with the homespun CLI: every capability the CLI exposes is reachable here.

MCP tools are request/response, so there is no long-lived "watch". To see what changed you poll get_feed_events with the cursor from the previous call (pass wait to long-poll, 0 to 30 seconds); to watch one collection, re-call list_rows with the prior next_cursor as since. Each tool description spells out the pattern for the model.

To keep the tool list compact (a flat 50+ tools would bloat client context and degrade selection), hot-path nouns stay discrete tools while multi-verb management nouns collapse into one tool each with a required action enum.

Hot-path (discrete) tools

Tool	What it does
`deploy_app`	Deploy a v2 app: an HTML document plus a capability manifest, hosted at its own URL. Omit `app_id` to create, pass it to redeploy in place (same URL, same data, same members). Takes `html` or `html_path`, optional `assets`, `visibility`, `slug`, `dry_run`, `force`.
`list_rows`	List rows in a collection. Doubles as the poll for a collection's current state: pass the prior `next_cursor` as `since`.
`get_row`	Fetch one row by `key` (a dedicated relay route, not a client-side scan).
`upsert_row`	Create a row, or return the existing one if `key` is already present (`deduped: true`). The only create-shaped verb.
`update_row`	Replace an existing row's `data`. Optional `if_match` optimistic lock.
`delete_row`	Soft-delete a row. Optional `if_match`.
`get_feed_events`	Poll the app's change feed for row creates/updates/deletes from any writer, human or agent. Optional `wait` (0-30s) long-poll.

Consolidated tools (one tool, required `action`)

Tool	Actions
`apps`	`list` · `show` · `update` · `share_link_rotate` · `delete` · `wake` · `domain_set` · `domain_status` · `domain_remove`
`members`	`add` · `list` · `set_role` · `remove` · `roles`
`grants`	`mint` · `list` · `revoke`
`ingest`	`list` · `rotate` · `set_signing_secret` · `clear_signing_secret`
`attachments`	`upload` · `fetch` · `presign` · `finalize` · `download` · `show` · `list` · `delete` · `mint_token` · `revoke_token` · `list_tokens`
`taste`	`get` · `set` · `clear`
`key`	`list` · `mint` · `revoke`
`feedback`	`create` · `list`
`agent`	`whoami` · `claim` · `logout`
`community`	`publish` · `get_config_contract` · `install` · `list_pending` · `get_submission` · `approve` · `reject` · `set_trust_level`
`publisher`	`claim` · `get` · `update`
`review`	`create` · `respond` · `report` · `remove` · `unhold`

Single-purpose tools

Tool	What it does
`get_skill`	Fetch the relay's auto-updating guide (unauthenticated) to self-teach the workflow.

Attachments take and return file paths: upload reads an absolute file_path; download writes to an absolute out_path (or returns base64 when omitted). For real media, presign then PUT then finalize avoids moving bytes through the tool call.

One data primitive. Everything an app stores is a collection: a named, mutable, queryable set of rows, each with a key, a data payload, an optimistic-lock version and an author. Every write also lands on the app's ordered change feed. Declare a collection appendOnly: true in the manifest when you want a journal (an audit trail, a submission log) rather than mutable state.

Not exposed (and why)

The CLI's config show is replaced by agent → whoami (resolved relay URL, active profile, and whether a key is set; no secrets).
agent register is not a tool. The server auto-registers on first use and shares the CLI's key store; agent → claim binds it to a human afterwards.
demo (the interactive terminal tour) and the CLI self-updater are terminal concerns with no agent use; omitted.

Typical flow

deploy_app with your HTML plus an x-homespun-manifest declaring the app's collections and which roles may read, write and delete each. Returns { app_id, url, ... }.
Give the url to the owner, and invite anyone else with members (action: add).
get_feed_events with wait: 25 in a loop, passing the prior cursor as since, to see what people do.
Read and write the same data with list_rows / upsert_row / update_row, and ship changes with deploy_app again, passing app_id.

MCP registry

server.json (in this package) carries the metadata for the official MCP registry. Publishing there is a follow-up step for the maintainer.

License

MIT, see LICENSE.

Install

Tools (20)

deploy_applist_rowsget_rowupsert_rowupdate_rowdelete_rowget_feed_eventsapps

Configuration

Environment variables

HOMESPUN_API_KEYsecret

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).

HOMESPUN_URL

Homespun relay base URL. Defaults to the hosted relay https://homespun.dev; set this to point at a different relay.

HOMESPUN_AGENT_NAME

Display name for the auto-registered agent on the relay.

HOMESPUN_REGISTER_SECRETsecret

Registration secret, required only for relays running REGISTRATION_MODE=secret.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "homespun": {
      "command": "npx",
      "args": [
        "-y",
        "@homespunapps/mcp@1.6.13"
      ],
      "env": {
        "HOMESPUN_API_KEY": "<YOUR_HOMESPUN_API_KEY>",
        "HOMESPUN_URL": "<YOUR_HOMESPUN_URL>",
        "HOMESPUN_AGENT_NAME": "<YOUR_HOMESPUN_AGENT_NAME>",
        "HOMESPUN_REGISTER_SECRET": "<YOUR_HOMESPUN_REGISTER_SECRET>"
      }
    }
  }
}

Model Context Protocol (MCP) Server: dev.homespun/homespun

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

deploy_app

list_rows

get_row

upsert_row

update_row

delete_row

get_feed_events

apps

members

grants

ingest

attachments

taste

key

feedback

agent

community

publisher

review

get_skill

@homespunapps/mcp

Runtime requirement: Node.js >= 20

Quickstart

Claude Desktop

Cursor

Generic MCP host

Configuration

Tools

Hot-path (discrete) tools

Consolidated tools (one tool, required action)

Single-purpose tools

Not exposed (and why)

Typical flow

MCP registry

License

Install

Configuration

Consolidated tools (one tool, required `action`)