List Apps
List the caller's Charming apps: owned ones plus apps shared with them (accepted invites, marked `[shared with you]`; a read-only share also reads `(view-only)`).
MCP name: list_apps
Tool contract
{
"annotations": {
"destructiveHint": false,
"openWorldHint": false,
"readOnlyHint": true,
"title": "List Apps"
},
"description": "List the caller's Charming apps: owned ones plus apps shared with them (accepted invites, marked `[shared with you]`; a read-only share also reads `(view-only)`). Use this to find an app's ID before opening or editing it. Each app's `description` is a search-friendly summary to match the user's words against. Paginate with `cursor` from a prior call's `nextCursor`. Give the user `shareUrl`, never a link built from `url`.",
"execution": {
"taskSupport": "forbidden"
},
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cursor": {
"description": "Opaque cursor from a prior call's `nextCursor` to fetch the next page.",
"type": "string"
},
"limit": {
"description": "Max apps to return (1-100, default 50).",
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
"type": "object"
},
"name": "list_apps",
"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"
},
"apps": {
"description": "Apps on this page, ordered by creation time newest-first.",
"items": {
"additionalProperties": false,
"properties": {
"appName": {
"description": "URL-safe slug for the app, unique per owner. Distinct from manifestId and displayName, and stable across edits — use rename_app to change it (the title changing does NOT change the slug).",
"type": [
"string",
"null"
]
},
"capabilities": {
"additionalProperties": false,
"description": "Capabilities the app's manifest declares.",
"properties": {
"connectOrigins": {
"description": "Exact https and wss origins injected into the app CSP connect-src so browser fetch, WebSocket, and EventSource can reach them (e.g. [\"https://api.example.com\", \"wss://stream.example.com\"]). Omitted when the app declares none.",
"items": {
"type": "string"
},
"type": "array"
},
"exports": {
"description": "Names of routes this app shares with the user's other apps, which reach them only when their own manifest imports this app. An app still on the legacy `2026-04-30` manifest shares every route, not only these.",
"items": {
"type": "string"
},
"type": "array"
},
"frameHosts": {
"description": "External https origins the app may embed, added to the app CSP frame-src (e.g. [\"https://www.youtube.com\"]). Omitted when the app declares none.",
"items": {
"type": "string"
},
"type": "array"
},
"imageHosts": {
"description": "External https image hosts injected into the app CSP img-src (e.g. [\"covers.openlibrary.org\"]). Omitted when the app declares none.",
"items": {
"type": "string"
},
"type": "array"
},
"imports": {
"description": "Capability tokens the app depends on (e.g. \"charming:storage/[email protected]\", \"charming:browser/[email protected]\").",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"imports",
"exports"
],
"type": "object"
},
"claimed": {
"description": "True if the app is owned by an authenticated user (i.e. has been claimed). list_apps only ever returns apps owned by the caller, so this is always true today; exposed for forward-compatibility with shared/discoverable listings.",
"type": "boolean"
},
"description": {
"description": "Search-friendly summary written by the creating agent. Match user intent (\"open my protein tracker\", \"log food\") against this rather than display name alone. Null on apps created before descriptions existed and not yet backfilled.",
"type": [
"string",
"null"
]
},
"displayName": {
"description": "Human-readable name.",
"type": "string"
},
"id": {
"description": "App UUID. Pass to get_app to render or get_app_source to read.",
"type": "string"
},
"lastUpdatedAt": {
"description": "ISO-8601 timestamp of the last write to this app's row (create, update_app, set_remixable, unset_remixable, claim, version pointer edits, etc.). Use for recency cues and \"what did I work on most recently\" surfaces. Not the sort key — apps are ordered by creation time, so sort client-side by this field if you need recency order.",
"type": "string"
},
"revision": {
"description": "Server-owned app source revision. Historical null counters read as 0; new apps start at 1; each successful source write advances it once. Pass this value through `expected_revision` when guarding update_app.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"role": {
"description": "`owner` = your personal app. `collaborator` = shared with you via an accepted invite (edit + run, but not share/delete/transfer). `end-user` = shared use-and-write-data (run the app and write its data, but cannot edit the app source). `viewer` = shared read-only (open and read, but no edits or mutating ops). `team-admin` / `team-member` = owned by a team you belong to; admins get full control, members can edit + run.",
"enum": [
"owner",
"collaborator",
"end-user",
"viewer",
"team-admin",
"team-member"
],
"type": "string"
},
"shareUrl": {
"description": "The link to give humans whenever the user wants to open or share the app. Friendly /<handle>/<app-name> form when the OWNER has a live handle and the app a slug, /app/<uuid> otherwise. Always token-free — safe to show, paste, and send. Not an API base: appending /api/<op> to the friendly form 404s; use `url` for machine calls.",
"type": "string"
},
"url": {
"description": "Machine URL for the app (stable /app/<uuid> form, token-free). When giving the user a link, use shareUrl instead.",
"type": "string"
}
},
"required": [
"id",
"role",
"displayName",
"revision",
"description",
"url",
"shareUrl",
"lastUpdatedAt",
"claimed",
"capabilities"
],
"type": "object"
},
"type": "array"
},
"nextCursor": {
"description": "Opaque cursor for the next page. Pass back as `cursor` on the next list_apps call. Absent on the final page.",
"type": "string"
},
"ok": {
"const": true,
"description": "Indicates success. Errors arrive as content with isError:true.",
"type": "boolean"
}
},
"required": [
"ok",
"apps"
],
"type": "object"
}
}