Share App with a User

Invite someone (by Charming handle or email) to one of your apps, OR change the role of someone you already invited.

MCP name: share_app

Tool contract

{
  "annotations": {
    "destructiveHint": true,
    "openWorldHint": true,
    "readOnlyHint": false,
    "title": "Share App with a User"
  },
  "description": "Invite someone (by Charming handle or email) to one of your apps, OR change the role of someone you already invited. Use this when the user wants to give a specific person access to an app, or to change what an existing collaborator/end-user/viewer can do. Creates a PENDING invitation: the invitee has no access until the eligible signed-in account chooses Open app from the email or Charming Home; that action creates the durable grant before entering the app. Pick a role: `collaborator` (default) can open, edit, and run the app (shared state, same data); `end-user` can open the app and write its data (record entries, save state) but cannot edit the app source; `viewer` can only open and use the read-only surface — viewers cannot edit, run mutating ops, or change anything. If the grantee already has a share, calling this again WITH a `role` changes their role in place (status `updated`, no new invitation, no second email) — this is how you flip a collaborator to an end-user and back; re-sharing WITHOUT a `role` leaves the existing role untouched. No share role can ever share, delete, or transfer the app. The invitee does NOT need a Charming account first — inviting an email with no account stores a pending invitation and emails them a sign-up link; the eligible grant appears after they register and verify that email (an unknown handle still errors, since there is no address to reach). Revoke anytime with `unshare_app`.",
  "execution": {
    "taskSupport": "forbidden"
  },
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "properties": {
      "app_id": {
        "description": "The app ID (UUID) to share",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
        "type": "string"
      },
      "grantee": {
        "description": "The invitee's Charming handle (e.g. `ada` or `@ada`) or account email",
        "minLength": 1,
        "type": "string"
      },
      "role": {
        "description": "The access level: `collaborator` (default — edit and run), `end-user` (run + write data, not edit source), or `viewer` (read-only)",
        "enum": [
          "collaborator",
          "end-user",
          "viewer"
        ],
        "type": "string"
      }
    },
    "required": [
      "app_id",
      "grantee"
    ],
    "type": "object"
  },
  "name": "share_app",
  "outputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "advisories": {
        "description": "Structured non-fatal advisories, including authoring issues and unread staff feedback responses. Each advisory.summary is also appended to the text content for the LLM path.",
        "items": {
          "additionalProperties": false,
          "properties": {
            "data": {
              "additionalProperties": {},
              "description": "Kind-specific structured payload. Shape varies per advisory kind.",
              "propertyNames": {
                "type": "string"
              },
              "type": "object"
            },
            "doc_url": {
              "description": "Optional docs pointer for this advisory kind.",
              "type": "string"
            },
            "kind": {
              "description": "Stable advisory identifier (e.g. \"legacy-bridge\").",
              "type": "string"
            },
            "severity": {
              "description": "Severity; omitted advisories are treated as 'info'.",
              "enum": [
                "info",
                "warn"
              ],
              "type": "string"
            },
            "summary": {
              "description": "Agent-facing summary. Self-sufficient; no extra context required.",
              "type": "string"
            },
            "userSummary": {
              "description": "End-user-facing summary. Set when the advisory should render in-app.",
              "type": "string"
            }
          },
          "required": [
            "kind",
            "summary"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "grantee": {
        "description": "The resolved grantee (handle when set, else email) the invitation was sent to.",
        "type": "string"
      },
      "message": {
        "description": "Consequence copy the agent should surface verbatim: the invitee has no access until they choose Open app, and what their role permits after the durable grant succeeds.",
        "type": "string"
      },
      "ok": {
        "const": true,
        "description": "Indicates success. Errors arrive as content with isError:true.",
        "type": "boolean"
      },
      "status": {
        "description": "Sharing creates an invitation, not access. `pending` = the grantee has a Charming account and gets access only when that account chooses Open app. `invited` = the email has no account yet; it becomes a pending share once they register and verify that address. `updated` = the grantee already had a share and re-sharing with a `role` changed it in place (no new invitation, no second email).",
        "enum": [
          "pending",
          "invited",
          "updated"
        ],
        "type": "string"
      }
    },
    "required": [
      "ok",
      "status",
      "grantee",
      "message"
    ],
    "type": "object"
  }
}