What is add-app-tool?

A guide for creating an MCP App: an agent tool paired with an interactive HTML screen shown inside a sandboxed frame.

Use it to build tools where a person must interact with tables, forms, approvals, or other live visual controls in an MCP-compatible client.

It helps decide when a visual interface is genuinely needed and explains the extra work of keeping the screen and text fallback consistent.

add-app-tool — Skill for Claude Code by cyanheads

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

Any agent

npx skills add cyanheads/cpsc-recalls-mcp-server --skill add-app-tool

Clone the repo

git clone --depth 1 https://github.com/cyanheads/cpsc-recalls-mcp-server

Made for: Claude Code.

Or install cpsc-recalls-mcp-server, the plugin that ships this one along with the rest of its 32 skills, 1 MCP server.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/skills/cyanheads/cpsc-recalls-mcp-server/add-app-tool/github.svg)](https://agentmods.dev/skills/cyanheads/cpsc-recalls-mcp-server/add-app-tool)

Your own site

<a href="https://agentmods.dev/skills/cyanheads/cpsc-recalls-mcp-server/add-app-tool"><img src="https://agentmods.dev/badge/skills/cyanheads/cpsc-recalls-mcp-server/add-app-tool/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/skills/cyanheads/cpsc-recalls-mcp-server/add-app-tool"><img src="https://agentmods.dev/badge/skills/cyanheads/cpsc-recalls-mcp-server/add-app-tool.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 41 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.

When invoked 2,891 The whole file, excluding the scripts and references it only reads on demand.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin 100% copy Near-identical to another mod in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.00041	$0.02891
Opus 5	$0.00020	$0.01445
Sonnet 5	$0.00008	$0.00578
Haiku 4.5	$0.00004	$0.00289

Measured 10d ago against content hash 96f3fdedf0a4, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-10, from the pricing page.

Security

Grade A, and why

add-app-tool scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 10d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

Origin

This is a copy

100% identical to add-app-tool — 0 lines differ, which has more behind it and is treated as the original. This page carries a canonical link to it rather than competing with it.

skills/add-app-tool/SKILL.md · 245 lines

How it starts

The opening of the file, as written. The whole thing — 245 lines — stays where its author put it; the contents beside it link to each section on GitHub.

When to Use

App tools are rarely the right choice. Reach for one only when all of the following hold:

A human will actively interact with the result in real time — not just an LLM consuming text.
The target deployment runs in a client that supports MCP Apps. Many clients (Claude Code, Cursor, most chat UIs) are tool-only and will only ever see the format() text fallback you have to maintain anyway.
The interaction the UI enables — scrubbing a dense table, approving a multi-step plan, filling a structured form — is core to the workflow, not nice-to-have rendering.

App tools cost more than standard tools: an iframe + CSP setup, app.ontoolresult / callServerTool plumbing, host-context wiring (theme, fonts, styles), and a format() text path that has to be content-complete because most clients see only that. Two surfaces to keep in sync, two failure modes per change.

Default to add-tool. This skill is the how-to once that bar is cleared — the "whether to" decision belongs in design-mcp-server.

Context

MCP Apps extend the standard tool pattern with an interactive HTML UI rendered in a sandboxed iframe by the host. Each MCP App consists of two definitions:

App tool (.app-tool.ts) — uses appTool() builder, declares resourceUri pointing to the UI resource
App resource (.app-resource.ts) — uses appResource() builder, serves the bundled HTML

Both builders are exported from @cyanheads/mcp-ts-core. They handle _meta.ui.resourceUri, the compat key (ui/resourceUri), and the correct MIME type (text/html;profile=mcp-app) automatically.

For the full API, Context interface, and error codes, read the framework's CLAUDE.md/AGENTS.md (loaded at session start).

Steps

Confirm the three conditions in "When to Use" apply — if any is uncertain, default to add-tool instead. Then gather the tool's name, purpose, input/output shape, and what the UI should display from the user's request — ask only if genuinely absent
Choose a URI — convention: ui://{{tool-name}}/app.html
Create the app tool at src/mcp-server/tools/definitions/{{tool-name}}.app-tool.ts
Create the app resource at src/mcp-server/resources/definitions/{{tool-name}}-ui.app-resource.ts
Register both in the project's existing createApp() arrays (directly in src/index.ts for fresh scaffolds, or via barrels if the repo already has them)
Run bun run devcheck — the linter validates _meta.ui and cross-checks tool/resource pairing
Smoke-test with bun run rebuild && bun run start:stdio (or start:http)

Read the full file on GitHub · 245 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

10d ago First seen · 245 lines · 41 tokens per session scan A 96f3fdedf0a4

Subscribe to this mod's changes

add-app-tool is a skill published in the GitHub repository cyanheads/cpsc-recalls-mcp-server (1 stars, last pushed 16d ago), licensed Apache-2.0. It adds 41 tokens to every session and 2,891 once invoked, about $0.0002 per session on Opus 5. A static security scan graded it A with 0 findings. It is 100% identical to add-app-tool, differing in 0 lines, and is treated as a copy.

Building agents Frontend ai-agents bun consumer-safety cpsc mcp mcp-server

add-app-tool

Getting it into your agent

Wrote this? Show the measurements

What it costs to keep this loaded

Grade A, and why

Nothing flagged

This is a copy

How it starts

When to Use

Context

Steps

What this file has done since we first saw it

Other skills, from other repositories

bun-runtime-templating

bun-guides-html-rewriter

add-app-tool

add-app-tool

add-app-tool

add-app-tool