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, or get_app are 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:

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.

1. Read the starter guide at usecharming.com/build-mcp.md.
2. Read the design guide at usecharming.com/design.md before writing UI code.
3. Create the first version with create_app({ description, module, ui, styles? }). description is required.
4. Give the user the returned app URL and app_id.
5. 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.
6. Offer one concrete next iteration, then call update_app only after the user agrees.
7. If the user hits a Charming limitation, call submit_feedback({ app_id, text }) instead of silently working around it.

Charming exposes 24 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:

• module is 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 optional meta.icon of one emoji plus a hex background, and capabilities.imports listing only what the app uses.
  • routes: an array of operations. Each has op (unique), method, path, title, description, inputSchema, outputSchema, annotations, optional public and examples, and a handler(input, { env, ctx, request }) that returns a JSON-compatible value. Set annotations.readOnlyHint to true on reads, or query_app and viewers cannot call them.
• ui is one inline JavaScript program that populates #app and calls the backend through window.charming.api(manifest.id).<op>(input), which resolves to the value directly and throws on failure.
• env.storage is Workers KV with only .get(key), .put(key, value), .delete(key), and .list(). It stores JSON-compatible values directly: never JSON.stringify before put or JSON.parse after get.
• 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 as textContent rather than replacing innerHTML, so the user's focus, selection, and typing survive.
• window.charming also carries what a shared or embedded app needs: viewer.role and viewer.can(op) to render only what this visitor may do, user for the caller's public identity, login() to trigger sign-in, assets and images for files and pictures, plus openLink, sendFollowUp, updateContext, recordAction, and isConnected / onConnectionChange. Neither viewer nor user is 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 a data: URL. Both hosts inject a CSP that blocks a cross-origin images.proxy(url) URL.
• Do not manage tokens in UI code; credentials attach automatically.
• The ui program runs as a classic script, so no ESM syntax and no top-level await.
• No Node APIs, no DOM APIs in the backend, no external UI scripts, no native form submit, and no alert, confirm, or prompt (they silently no-op in the sandboxed iframe). Outbound backend fetch is 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:

Two allowlists sit outside capabilities, both under permissions, and both take exact https://host origins:

• permissions.server.fetch gates 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.

Codex notes

• In Codex app sessions with a browser tool available, open the returned URL in Codex's in-app browser when MCP Apps inline UI does not visibly mount in the conversation.
• Codex CLI users who connect Charming by hand instead of installing the plugin use this config.toml entry:

[mcp_servers.charming]
url = "https://charm.ing/mcp"