What is add-app-tool?

A development guide for creating an MCP App: a tool that combines an AI-callable action with an interactive webpage. MCP, the Model Context Protocol, lets AI clients use tools and other connected capabilities.

Use it to build tools for workflows such as reviewing dense tables, approving multi-step plans, or filling in structured forms when the target client supports MCP Apps.

It helps you decide when an interactive interface is actually needed and explains the extra work of keeping the webpage and text response consistent across clients.

add-app-tool — Skill for Claude Code and Codex by cyanheads: A development guide for creating an MCP App: a…

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.

agentmods

npx agentmods add skills/cyanheads/reference-data-mcp-server/add-app-tool

Any agent

npx skills add cyanheads/reference-data-mcp-server --skill add-app-tool

Clone the repo

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

Made for: Claude Code, Codex.

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

Your own site

<a href="https://agentmods.dev/skills/cyanheads/reference-data-mcp-server/add-app-tool"><img src="https://agentmods.dev/badge/skills/cyanheads/reference-data-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. Scan, not verified.

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	$0.00041	$0.02891
Opus 5	$0.00020	$0.01445
Sonnet 5	$0.00008	$0.00578
Haiku 4.5	$0.00004	$0.00289

Measured 4d ago against content hash 96f3fdedf0a4, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, 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 4d 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.

4d 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/reference-data-mcp-server (1 stars, last pushed 10d 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 bun countries elements http-status mcp mcp-server

verify-task

Verify a work item is actually done by running the V- validation rows its issue cites. Maps V- IDs to the CI step / test command via VALIDATION.md, runs them, reports pass/fail per row.

tikoci/rosetta · 47 tokens

promote-idea

Promote an Inbox bullet from BACKLOG.md to either a GitHub issue (work commitment) or a briefing (briefings/B-NNNN-.md, research/decision support). Asks which based on whether the work is committed or still needs thinking. Removes the original bullet.

tikoci/rosetta · 63 tokens

add-app-tool