charming
VerifiedCreate, update, inspect, or troubleshoot Charming-hosted interactive web apps via the Charming MCP server, or connect an AI client (Claude, Cursor, Codex, Gemini CLI, ChatGPT) to Charming.
Charming
Overview
Use this skill when the user asks to create an app with Charming, edit an existing Charming app, connect the Charming MCP server, or inspect Charming-generated app source.
Charming is a hosted service that generates, hosts, and updates small interactive web apps. Each app gets a real URL, persistent storage, and inline rendering inside MCP Apps-capable chat clients. It has two authoring paths:
- MCP tools (preferred): use this path whenever Charming tools such as
create_app,update_app,list_apps, orget_appare available to you. - HTTP API (fallback): use only when Charming MCP tools are not available and you have outbound HTTP access.
Connect
Charming is a remote server; there is nothing to clone, build, or run locally. Add the endpoint to your client's MCP settings:
| Client | Endpoint |
|---|---|
| Claude, Claude Code, Cursor, Codex, Gemini CLI, and most MCP clients | https://charm.ing/mcp |
| ChatGPT | the Charming listing in the ChatGPT Apps directory is one click; https://charm.ing/mcp/chatgpt is the Developer Mode fallback |
Charming's MCP endpoints always require a bearer token. OAuth with Dynamic Client Registration bootstraps one automatically on first connect: clients that support it show a one-time consent screen, with no API key to paste. Anonymous creation with no token is available on the HTTP path only (POST https://charm.ing/app), and an unclaimed app has a 7-day TTL until someone claims it. To mint a token by hand, use device pairing: POST https://charm.ing/api/pair/start, then poll. Full auth guide: usecharming.com/auth.md. Per-client paste-strings and setup steps: usecharming.com/clients.txt.
MCP workflow
When Charming MCP tools are available, build with the tools directly. Do not use curl, fetch, shell HTTP calls, or the raw HTTP API for app creation.
- Read the starter guide at usecharming.com/build-mcp.md.
- Read the design guide at usecharming.com/design.md before writing UI code.
- Create the first version with
create_app({ description, module, ui, styles? }).descriptionis required. - Give the user the returned app URL and
app_id. - If the host does not render the app inline, share the returned URL so the user can open it directly. Do not claim the app is visible inline unless the host actually rendered it.
- Offer one concrete next iteration, then call
update_apponly after the user agrees. - If the user hits a Charming limitation, call
submit_feedback({ app_id, text })instead of silently working around it.
Charming exposes tools; connected clients discover them via tools/list. The core authoring set is create_app, update_app, get_app, get_app_source, list_apps, and delete_app. Beyond those, query_app / mutate_app run an app's backend operations without editing code; upload_asset stores static assets; share_app / unshare_app / list_app_shares, set_public / unset_public, and set_remixable / unset_remixable control access and remixing; set_template / unset_template publish an app as a copyable template and search_templates searches the public directory; rename_app, set_handle, and set_starter_prompt manage URLs and share prompts; submit_feedback / list_feedback capture app feedback. The full descriptions live in the README and usecharming.com/llms-full.txt.
Generated app code must follow the Charming contract:
moduleis one ES module with two named exports and no required default export:manifest: a plain literal, parsed statically, so no computed values. It carries$schema(the current dated manifest schema),id,meta.name, an optionalmeta.iconof one emoji plus a hex background, andcapabilities.importslisting only what the app uses.routes: an array of operations. Each hasop(unique),method,path,title,description,inputSchema,outputSchema,annotations, optionalpublicandexamples, and ahandler(input, { env, ctx, request })that returns a JSON-compatible value. Setannotations.readOnlyHinttotrueon reads, orquery_appand viewers cannot call them.
uiis one inline JavaScript program that populates#appand calls the backend throughwindow.charming.api(manifest.id).<op>(input), which resolves to the value directly and throws on failure.env.storageis Workers KV with only.get(key),.put(key, value),.delete(key), and.list(). It stores JSON-compatible values directly: neverJSON.stringifybeforeputorJSON.parseafterget.- Subscribe with
window.charming.onStateChange(cb)so the UI updates when the agent runs the app's operations from another session. Apply surgical updates such astextContentrather than replacinginnerHTML, so the user's focus, selection, and typing survive. window.charmingalso carries what a shared or embedded app needs:viewer.roleandviewer.can(op)to render only what this visitor may do,userfor the caller's public identity,login()to trigger sign-in,assetsandimagesfor files and pictures, plusopenLink,sendFollowUp,updateContext,recordAction, andisConnected/onConnectionChange. Neitherviewernoruseris an enforcement boundary; the server gates are.- To show an external image inside a Claude or ChatGPT embed, use
window.charming.images.load(url), which returns adata:URL. Both hosts inject a CSP that blocks a cross-originimages.proxy(url)URL. - Do not manage tokens in UI code; credentials attach automatically.
- The
uiprogram runs as a classic script, so no ESM syntax and no top-levelawait. - No Node APIs, no DOM APIs in the backend, no external UI scripts, no native form submit, and no
alert,confirm, orprompt(they silently no-op in the sandboxed iframe). Outbound backendfetchis not banned; it is off until declared, see capabilities below.
Declare only the capabilities the app uses in manifest.capabilities.imports; the host rejects strings it does not know, so never invent one:
| Import | Grants |
|---|---|
charming:storage/kv@1.0 | env.storage, the key-value store |
charming:storage/blob@1.0 | env.assets, for uploaded files |
charming:logging/emit@1.0 | env.log |
charming:network/fetch@1.0 | plain backend fetch, claimed apps only |
charming:secrets/fetch@1.0 | sealed env.fetch that substitutes {{secret:NAME}} into headers, claimed apps only |
charming:browser/<name>@1.0 | a claim-gated browser permission such as camera or microphone |
charming:app/<id>@x.y | operations from another app |
Two allowlists sit outside capabilities, both under permissions, and both take exact https://host origins:
permissions.server.fetchgates every backend egress path, plain and sealed alike. The import and the origins are both required: origins on their own persist but leave egress blocked (the server only warns), and the sealed path denies outright on an empty list.permissions.browser["img-src"]is required for external images. Without it the image simply does not render.
Legacy export default { fetch(request, env, ctx) } still works, and on a canonical app it serves as the unmatched-path fallback, but a legacy operation carries no method or read-only metadata: it defaults to POST and readOnly: false, so it cannot be reached through query_app or by a viewer. Author operations as routes. manifest.capabilities.exports belongs to the older manifest shape and is rejected outright by the current schema, and an app created over MCP must use the canonical contract. Editing an existing legacy app over MCP returns contract_migration_required: resend the full canonical source with migrate_contract: true, rewriting any legacy window.buildy call in the UI to window.charming.
// module
export const manifest = {
$schema: 'https://charm.ing/schema/app-manifest/2026-07-31.json',
id: 'counter',
meta: { name: 'Counter', icon: { emoji: '➕', bg: '#1f6e68' } },
capabilities: { imports: ['charming:storage/kv@1.0'] },
};
export const routes = [
{
op: 'increment',
method: 'POST',
path: '/api/increment',
title: 'Increment counter',
description: 'Increment the counter and return the new value.',
inputSchema: { type: 'object', properties: {}, additionalProperties: false },
outputSchema: {
type: 'object',
required: ['count'],
properties: { count: { type: 'integer' } },
additionalProperties: false,
},
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
handler: async (_input, { env }) => {
const count = ((await env.storage.get('count')) ?? 0) + 1;
await env.storage.put('count', count);
return { count };
},
},
];
// ui
const api = window.charming.api('counter');
const root = document.getElementById('app');
root.innerHTML = '<button id="b">+1</button><span id="c">0</span>';
const display = document.getElementById('c');
document.getElementById('b').onclick = async () => {
const { count } = await api.increment({});
display.textContent = count;
};
// e is { kind: 'state-changed', op, source: 'agent' | 'reconnect-resync', ts, result }.
// onStateChange returns an unsubscribe function.
window.charming.onStateChange((e) => {
if (e.source === 'reconnect-resync') {
// The connection was idle too long for the server to say what was missed.
// Refetch through a read route, or no-op until the next agent action.
return;
}
if (e.result && typeof e.result === 'object' && 'count' in e.result) {
display.textContent = String(e.result.count);
}
});
HTTP fallback
When Charming MCP tools are not available, follow usecharming.com/start.md and then usecharming.com/build-http.md. Prefer MCP setup first if the user asked for a connector or if the client can install the MCP server.
Output expectations
When creating or updating an app, end with the app URL, the app_id, what changed, and the next practical iteration.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |