Most MCP servers I've written do one thing: take arguments, run some code, hand back text. That's fine until the agent needs structured input from a human — an expense entry, a config object, a date range. Dumping a JSON template into the chat and hoping the user types it correctly is not a great experience.
The MCP Apps extension fixes that. Your server can also serve an HTML resource, and a compatible host renders it in a sandboxed panel next to the conversation. The user fills in a real form, and the values come back to the agent as a tool result.
In this walkthrough I'll build a small expense-app server with one tool and one form. It takes about 45–60 minutes and sits at intermediate level: you should be comfortable with TypeScript, npm, and editing a JSON config file.
What an MCP App actually is
MCP (Model Context Protocol) is an open JSON-RPC 2.0 protocol that lets an AI agent call tools and read resources from an external process. An MCP App is just an MCP server with one extra trick: it also exposes an HTML resource. The ui:// URI scheme is what marks that resource as UI rather than data, so the host routes it to the sandboxed panel instead of passing it to the model's context.
The round trip you're building looks like this:
- The agent decides the user needs structured input.
- It calls your tool,
add_expense. - The tool points at a UI resource through
_meta.ui.resourceUri:ui://expense/form.html. - The host renders that HTML next to the chat.
- The user submits the form and the values travel back as a tool result.
Pre-flight checks
Before touching any code, confirm these five things:
-
node -vandnpm -vboth print a current LTS version. If not, install LTS vianvmon macOS/Linux or the official installer. Check the MCP TypeScript SDK README for the exact minimum for the release you pick. - Your MCP client supports both base MCP and the MCP Apps extension. This matters: a client with only base MCP support will happily call your tools but never show a panel. Check the extensions list in your client's docs.
- The client is installed and you know how to fully restart it.
- You know the absolute path to your project folder — every config path below depends on it.
- No API keys needed. The local stdio demo requires no cloud account and no billing.
Otherwise: macOS 13+, Windows 11, or Ubuntu 22.04+ with a shell. Any OS with a current Node.js will run the code. Budget roughly 200 MB of disk for node_modules plus build output.
For the examples below I'll assume the project lives at /Users/anna/expense-app. On Windows that would be C:\\Users\\anna\\expense-app, with escaped backslashes when it goes into JSON.
Step 1: Scaffold the server and register one tool
Create the project, install the SDK, and set up TypeScript:
mkdir expense-app && cd expense-app
npm init -y
npm pkg set type=module
npm i @modelcontextprotocol/sdk zod
npm i -D typescript
npx tsc --init --outDir dist --rootDir src --module nodenext --target es2022
mkdir src
That type=module line is not optional — the SDK ships ES modules and a CommonJS project blows up at import time.
Now create src/index.ts with a single tool:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
const server = new McpServer({ name: "expense-app", version: "0.1.0" });
server.registerTool(
"add_expense",
{
title: "Add expense",
description: "Collects one expense entry from the user and returns it as structured data.",
inputSchema: { note: z.string().optional() },
},
async ({ note }) => ({
content: [{ type: "text", text: `Form context: ${note ?? "none"}` }],
})
);
await server.connect(new StdioServerTransport());
Build it and run it:
npx tsc
node dist/index.js
The tool definition is the entire contract the agent sees. No tool means nothing to call; no input schema means the agent can't build valid arguments.
How do you know it worked? node dist/index.js printing nothing and hanging is the correct behaviour for a stdio server — it's waiting for JSON-RPC on stdin. To actually inspect the tool, use the Inspector:
npx @modelcontextprotocol/inspector node dist/index.js
It prints a local URL and port in the terminal. Open exactly that URL (the port changes per run), click Connect, then List Tools. add_expense should appear with its schema.
One caveat I always mention: import paths and method names (registerTool vs tool) have shifted between SDK releases. Check the README of the version you actually installed.
Step 2: Serve the form and bind it to the tool
Create src/form.html with a minimal expense form:
<!doctype html>
<html>
<body>
<form id="f">
<label>Amount <input name="amount" type="number" step="0.01" required></label>
<label>Category
<select name="category">
<option>travel</option>
<option>software</option>
<option>office</option>
</select>
</label>
<button type="submit">Save expense</button>
</form>
<script>
// Handshake and message names come from the MCP Apps client library.
// Copy the current snippet from the MCP Apps docs for the version your host supports.
document.getElementById("f").addEventListener("submit", (e) => {
e.preventDefault();
const data = Object.fromEntries(new FormData(e.target).entries());
window.parent.postMessage({ type: "tool-result", payload: data }, "*");
});
</script>
</body>
</html>
Register it as a resource, then point the tool at it using _meta:
import { readFileSync } from "node:fs";
const FORM_URI = "ui://expense/form.html";
const formHtml = readFileSync(new URL("./form.html", import.meta.url), "utf8");
server.registerResource(
"expense-form",
FORM_URI,
{ mimeType: "text/html;profile=mcp-app", title: "Expense form" },
async () => ({
contents: [{ uri: FORM_URI, mimeType: "text/html;profile=mcp-app", text: formHtml }],
})
);
server.registerTool(
"add_expense",
{
title: "Add expense",
description: "Opens a form so the user can enter one expense and returns the values.",
inputSchema: { note: z.string().optional() },
_meta: { ui: { resourceUri: FORM_URI } },
},
async ({ note }) => ({ content: [{ type: "text", text: `Opened form. Context: ${note ?? "none"}` }] })
);
The agent knows about tools, not files. _meta.ui.resourceUri is the glue that says "call this tool, then render whatever lives at this URI." The text/html;profile=mcp-app MIME type and the exact meta key names belong to the MCP Apps extension, so verify them against the spec version your client implements before you ship anything.
To check it: rebuild with npx tsc, restart the Inspector, list Resources and confirm ui://expense/form.html is there, then call add_expense and open the Resources tab preview. You should see a rendered amount + category form, not raw HTML source. If you copy the HTML into dist/, keep in mind that readFileSync resolves relative to the compiled file, not to src/.
Step 3: Register the server in your agent and test end to end
Now edit the client config. Claude Desktop keeps it at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows:
{
"mcpServers": {
"expense-app": {
"command": "node",
"args": ["/Users/anna/expense-app/dist/index.js"]
}
}
}
Copy the form next to the compiled output, smoke-test the process manually, then restart the client:
cp src/form.html dist/form.html
node dist/index.js # manual smoke test, Ctrl+C to stop
The client spawns your server as a child process. That child inherits no shell environment and resolves no paths, which is why a bare node plus an absolute script path is the only combination that reliably works. And the restart has to be a full one — quit from the tray or menu bar, not just closing the window, because config is only read at startup.
Once the client is back up, the tool icon should show up in the chat input. Ask something like "Add an expense for a client dinner", let the agent pick add_expense, and watch for the tool-call card and the form panel. Fill in an amount and a category, submit, and check that the values arrive back in the conversation as the tool result.
The failure modes I'd check first
A few things account for almost every "why isn't my UI showing up" moment:
-
Missing
_meta. Register the resource but forget the_metablock and the Inspector listsadd_expenseandexpense-formas two unrelated items. The chat just returnsOpened form. Context: nonewith no panel. This one line is the most common cause. -
A CommonJS project.
npm pkg set type=moduleexists for a reason. -
Wrong path to the HTML. The build output and the HTML need to sit together, or
readFileSyncthrows at startup. - No full restart. Config changes silently do nothing until the client actually reloads.
- A client without the MCP Apps extension. Tools work, panels never render. Confirm support in the docs first.
- Copy-pasted SDK details from an older tutorial. Import paths, method names, and meta keys drift between releases.
Takeaway
An MCP App is a small idea with a big UX payoff: one extra registered resource, one _meta pointer, and your tool stops returning a wall of text and starts returning a form. Build the tool first, verify it in the Inspector, then add the UI and bind it. If you debug in that order, the only remaining variable is the client config — which is the easiest one to fix.
This article was originally published on AI Release — https://ai-release.org. If you want more write-ups like this one, the channel is at https://t.me/ai_release1.
Happy building.
Top comments (0)