Get App
Fetch an existing app by ID and render it inline.
MCP name: get_app
Tool contract
{
"_meta": {
"ui": {
"resourceUri": "ui://charming/app-v2"
},
"ui/resourceUri": "ui://charming/app-v2"
},
"annotations": {
"destructiveHint": false,
"openWorldHint": false,
"readOnlyHint": true,
"title": "Get App"
},
"description": "Fetch an existing app by ID and render it inline. Use this to open, re-render, or continue working with an app the caller already has; call list_apps first to find the ID. Before changing the app's source, read the build guide with read_docs({ path: \"build-mcp.md\" }). Give the user `shareUrl` to open or share the app; the `url` field is machine-only and carries a write-capable access token.",
"execution": {
"taskSupport": "forbidden"
},
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"app_id": {
"description": "The app ID (UUID)",
"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"
}
},
"required": [
"app_id"
],
"type": "object"
},
"name": "get_app",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"$schema": {
"description": "Exact manifest schema URL. Omitted for legacy apps.",
"type": "string"
},
"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"
},
"api": {
"additionalProperties": false,
"description": "The routes the app's author wrote into its source.",
"properties": {
"baseUrl": {
"description": "Origin and app prefix the routes live under.",
"type": "string"
},
"operations": {
"description": "Discovered routes in author order.",
"items": {
"additionalProperties": false,
"properties": {
"description": {
"description": "Author-supplied prose description.",
"type": "string"
},
"destructive": {
"description": "True when the route destroys data. Default false unless derived as such.",
"type": "boolean"
},
"discoveredFrom": {
"description": "Sources that contributed this operation (precedence order).",
"items": {
"enum": [
"routes_export",
"manifest_export",
"module_route"
],
"type": "string"
},
"type": "array"
},
"examples": {
"description": "Example inputs the app's author supplied.",
"items": {
"additionalProperties": false,
"properties": {
"description": {
"type": "string"
},
"input": {},
"output": {}
},
"type": "object"
},
"type": "array"
},
"idempotent": {
"description": "True when repeating the call with the same input has no further effect.",
"type": "boolean"
},
"input": {
"description": "JSON Schema for the field. Canonical source declares it as `route.inputSchema` or `route.outputSchema`."
},
"manifestExport": {
"description": "Original capability-export string when discovered via `manifest_export`.",
"type": "string"
},
"method": {
"description": "HTTP method the route accepts.",
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE"
],
"type": "string"
},
"op": {
"description": "Route name, as the author wrote it in the app's `routes` array.",
"type": "string"
},
"openWorld": {
"description": "True when the route may reach beyond the app, such as the network. Default true.",
"type": "boolean"
},
"output": {
"description": "JSON Schema for the field. Canonical source declares it as `route.inputSchema` or `route.outputSchema`."
},
"path": {
"description": "Path under the app, e.g. `/api/increment`.",
"type": "string"
},
"public": {
"description": "True when the route is visible to discovery. Default true.",
"type": "boolean"
},
"readOnly": {
"description": "True when the route is a safe read (resolved from author intent + derivation).",
"type": "boolean"
},
"title": {
"description": "Short author-supplied title for the operation.",
"type": "string"
},
"tool": {
"description": "`query_app` for a read-only route, `mutate_app` otherwise.",
"enum": [
"query_app",
"mutate_app"
],
"type": "string"
},
"url": {
"description": "Full URL (origin + app prefix + path).",
"type": "string"
}
},
"required": [
"op",
"method",
"path",
"url",
"readOnly",
"destructive",
"idempotent",
"openWorld",
"public",
"tool",
"discoveredFrom"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"baseUrl",
"operations"
],
"type": "object"
},
"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"
]
},
"appVersion": {
"description": "Canonical apps return decimal String(revision). Legacy apps return their stored effective SemVer.",
"type": "string"
},
"description": {
"description": "Search-friendly summary of what the app does. Null on apps created before descriptions existed; agents are nudged to backfill on the next update_app.",
"type": [
"string",
"null"
]
},
"displayName": {
"description": "Human-readable name shown in app listings and headers.",
"type": "string"
},
"id": {
"description": "UUID of the opened app.",
"type": "string"
},
"manifestId": {
"description": "Stable manifest identifier declared by the app module. Distinct from `id` (DB primary key) — surface this when discussing the app with the user.",
"type": "string"
},
"manifestVersion": {
"description": "Deprecated public contract marker. Canonical apps return null; legacy apps return their stored contract date.",
"type": [
"string",
"null"
]
},
"ok": {
"const": true,
"description": "Indicates success. Errors arrive as content with isError:true.",
"type": "boolean"
},
"recentIssues": {
"additionalProperties": false,
"description": "Runtime failures recorded against the current app revision since it was published (#1133): contract misses, runtime JS errors, CSP violations, and failed API calls. Present only when the current revision has at least one such event — absence means a clean render. The same summary is appended to the text content. Fetch full detail with GET /app/:id/activity.",
"properties": {
"counts": {
"additionalProperties": false,
"description": "Issue counts per category.",
"properties": {
"apiFailures": {
"description": "Failed calls to the app API proxy, including calls refused at the app run ceiling, which are recorded one row per 10-second window.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"appLoadErrors": {
"description": "Caught manifest-resolve / app load failures the bridge swallowed before they became an unhandled rejection.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"contractMisses": {
"description": "Publish-time UI/backend contract validation failures.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"cspViolations": {
"description": "Content-Security-Policy violations (e.g. an external image blocked by img-src).",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"externalResourceFailures": {
"description": "Failed external image requests, including failures caught by app code.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"runtimeErrors": {
"description": "Runtime JS errors and unhandled rejections reported by the rendered page.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
}
},
"required": [
"contractMisses",
"runtimeErrors",
"cspViolations",
"apiFailures",
"externalResourceFailures",
"appLoadErrors"
],
"type": "object"
},
"examples": {
"description": "Most recent example per non-empty category, newest first.",
"items": {
"additionalProperties": false,
"properties": {
"category": {
"description": "Which `counts` bucket this example illustrates.",
"enum": [
"contractMisses",
"runtimeErrors",
"cspViolations",
"apiFailures",
"appLoadErrors",
"externalResourceFailures"
],
"type": "string"
},
"kind": {
"description": "Underlying durable event kind: `diag_report` (runtime errors and CSP violations, distinguished by category), `contract_validation` (contract misses), `api_proxy_result` (API failures), `app_load_error` (caught load failures), or `image_proxy_result` (external image failures).",
"type": "string"
},
"summary": {
"description": "Compact one-line description.",
"type": "string"
},
"ts": {
"description": "ISO-8601 timestamp of the event.",
"type": "string"
}
},
"required": [
"ts",
"category",
"kind",
"summary"
],
"type": "object"
},
"type": "array"
},
"since": {
"description": "Set when the plan's window hid older issues: the cutoff the counts start from (ISO-8601).",
"type": "string"
},
"sinceRevision": {
"description": "The app revision the issues are attributed to (the current revision at call time). Legacy nulls normalize to 0.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"total": {
"description": "Failed calls counted for the current revision, read from the newest 1000 issue rows. One row can stand for a burst of refused calls, so this can exceed 1000. Use GET /app/:id/activity for the exact, paginated list.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
}
},
"required": [
"sinceRevision",
"total",
"counts",
"examples"
],
"type": "object"
},
"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"
},
"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/API URL for the app (stable /app/<uuid> form). Embeds a write-capable ?t= access token — NEVER show, paste, or send it to the user. Append /api/<op> to its path for out-of-band operation calls. For anything user-facing, use shareUrl instead.",
"type": "string"
}
},
"required": [
"ok",
"id",
"url",
"shareUrl",
"displayName",
"description",
"manifestId",
"revision",
"appVersion",
"manifestVersion",
"api"
],
"type": "object"
}
}ChatGPT metadata
ChatGPT adds or replaces these fields for progress messages and inline app rendering.
{
"_meta": {
"openai/outputTemplate": "ui://charming/chatgpt/app-v2",
"openai/toolInvocation/invoked": "App ready",
"openai/toolInvocation/invoking": "Opening app…",
"ui": {
"resourceUri": "ui://charming/chatgpt/app-v2"
},
"ui/resourceUri": "ui://charming/chatgpt/app-v2"
}
}