What is add-app-tool?

A guide for creating MCP tools with an interactive web interface. MCP Apps are tools whose results can include a small user-facing interface, such as a form or a table.

Use it to build an MCP tool with interactive screens for tasks such as reviewing dense tables, approving plans, or filling in structured forms.

It helps developers decide when an interface is genuinely needed and explains the extra work required to keep the interface and text response usable.

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/shift-mcp-server --skill add-app-tool

Clone the repo

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

Made for: Claude Code.

Or install shift-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/shift-mcp-server/add-app-tool.svg)](https://agentmods.dev/skills/cyanheads/shift-mcp-server/add-app-tool)

Your own site

<a href="https://agentmods.dev/skills/cyanheads/shift-mcp-server/add-app-tool"><img src="https://agentmods.dev/badge/skills/cyanheads/shift-mcp-server/add-app-tool.svg" alt="Measured on agentmods" 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 7d ago against content hash 96f3fdedf0a4, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-07, 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 7d 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.

7d 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/shift-mcp-server (1 stars, last pushed 15d 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 Claude Code Frontend Multi-Agent coordination mcp mcp-server model-context-protocol

sema-ui

Launch the Sema web UI at localhost:3030 — interactive pattern browser with 3D graph, search, and live updates. Use when the user asks to "open the UI", "show the graph", or wants visual access to the vocabulary.

emergent-wisdom/sema · 57 tokens

design-taste-frontend

Anti-slop frontend skill for landing pages, portfolios, and redesigns. The agent reads the brief, infers the right design direction, and ships interfaces that do not look templated. Real design systems when applicable, audit-first on redesigns, strict pre-flight check.

dmae97/omk · 61 tokens

clone-website

Reverse-engineer and clone one or more websites in one shot — extracts assets, CSS, and content section-by-section and proactively dispatches parallel builder agents in worktrees as it goes. Use this whenever the user wants to clone, replicate, rebuild, reverse-engineer, or copy any website. Also triggers on phrases…

dmae97/omk · 96 tokens

image-to-code

Elite website image-to-code skill for Codex. For visually important web tasks, it must first generate the design image(s) itself, deeply analyze them, then implement the website to match them as closely as possible. In Codex, it must prefer large, readable, section-specific images instead of tiny compressed boards…

dmae97/omk · 116 tokens

design-taste-frontend-v1

The original v1 taste-skill, preserved for projects depending on its exact behavior. The current default is design-taste-frontend (v2 experimental), which is a substantial rewrite. Use this v1 install name only if you need exact backward compatibility.