MCP Server Builder

Decision: standard server vs MCP App

Before writing code, determine which type the user needs:

If the user's server needs to return images, render charts, display interactive content, or bypass the 1MB limit, it's an MCP App. Otherwise, a standard server is simpler.

Quick reference: verified SDK versions (February 2026)

Always verify these against npm before starting — the SDK iterates fast.

Standard MCP server

Architecture

A standard MCP server exposes tools, resources, and prompts over a transport (Streamable HTTP for remote, stdio for local). Claude discovers tools via tools/list and calls them via tools/call.

Key patterns

Factory pattern (required for Streamable HTTP). Create a new McpServer instance per request for stateless operation. A shared singleton causes state collisions with concurrent users.

// server.ts
export function createServer(): McpServer {
  const server = new McpServer({ name: "My Server", version: "1.0.0" });
  // register tools here
  return server;
}

// main.ts — new server per request
app.all("/mcp", async (req, res) => {
  const server = createServer();
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
  res.on("close", () => { transport.close().catch(() => {}); server.close().catch(() => {}); });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

Use createMcpExpressApp from @modelcontextprotocol/sdk/server/express.js instead of raw Express. It sets up correct defaults.

Zod for input schemas. The SDK accepts Zod schemas directly — use them consistently.

structuredContent for rich data. Even in standard servers, structuredContent lets you return typed data alongside text content. Clients that understand it get structured access; others fall back to the text.

Tool annotations. Always include readOnlyHint, destructiveHint, idempotentHint for each tool. Helps hosts make safe decisions about automatic tool calling.

For complete standard server patterns, read: references/standard-server.md

MCP App server

MCP Apps extend a standard server with interactive UI. A tool declares a ui:// resource; when Claude calls the tool, the host renders the HTML in a sandboxed iframe and pipes the tool result to the iframe via postMessage.

When to use MCP Apps

• Displaying images, charts, maps, or any visual content inline in Claude
• Bypassing the 1MB tool-result size limit (images, PDFs, large data)
• Adding interactive controls (regenerate buttons, parameter sliders, pagination)
• Streaming partial results with live preview
• Any tool where "seeing" the output matters more than reading text about it

Core architecture

Server <── MCP (Streamable HTTP) ──> Host (Claude.ai) <── postMessage (JSON-RPC) ──> View (iframe)

Two registration calls link tool to UI:

1. registerAppTool(server, name, config, handler) — tool with _meta.ui.resourceUri
2. registerAppResource(server, name, uri, options, handler) — serves the bundled HTML

The host fetches the HTML, renders it in a sandboxed iframe, and delivers the tool result via the App Bridge (postMessage JSON-RPC).

Image delivery strategies

The chunked pattern is officially documented and recommended for binaries. It avoids all size limit concerns.

Critical rules (the top 3 bugs)

1. Register ALL event handlers BEFORE calling app.connect(). If you register ontoolresult after connect(), you miss the initial tool result. This is the single most common MCP App bug.

2. Bundle everything into one HTML file. The iframe runs under deny-by-default CSP. Separate JS/CSS files require CSP declarations and are nearly impossible to debug on Claude.ai web. Use vite-plugin-singlefile.

3. Separate content from structuredContent. content is small text for the model's context window. structuredContent is rich data for the View, hidden from the model. This separation is what bypasses the 1MB limit.

Complete MCP App implementation guide

Read references/mcp-apps-guide.md for:

• Full lifecycle walkthrough (5 phases)
• Complete server code with factory pattern, image store, TTL cleanup
• Complete client code with chunked loading, progress bar, theme adaptation
• Vite build setup with dual tsconfigs
• Capability negotiation and fallback for non-App hosts
• CSP, CORS, and _meta.ui.domain configuration
• Platform support matrix
• All debugging techniques and known cross-client bugs

Claude.ai-specific behaviors

Read references/claude-host.md for:

• Default CSP string
• Sandbox restrictions
• CORS domain computation (sha256(serverUrl).slice(0,32).claudemcpcontent.com)
• Display modes (inline, fullscreen)
• Platform support (web, desktop, mobile)
• Transport requirements (Streamable HTTP + SSE)

MCP Apps patterns (from official ext-apps docs)

Read references/mcp-apps-patterns.md for:

• App-only tools (hidden from model)
• Chunked binary loading (the full pattern with server + client code)
• Binary blob resources
• CSP and CORS configuration with examples
• Host theme adaptation (CSS variables, fonts, safe areas)
• Fullscreen toggle
• Model context updates from the View
• Large follow-up messages
• View state persistence
• Pausing heavy views when offscreen
• Streaming partial tool input for preview

Project setup checklist

Standard server

my-mcp-server/
├── package.json        (type: module, @modelcontextprotocol/sdk ^1.26.0)
├── tsconfig.json
├── server.ts           (createServer factory, tool registrations)
└── main.ts             (createMcpExpressApp, transport, shutdown)

MCP App server

my-mcp-app/
├── package.json        (+ @modelcontextprotocol/ext-apps ^1.0.1, vite, vite-plugin-singlefile)
├── tsconfig.json       (DOM libs for client code)
├── tsconfig.server.json (NodeNext for server code)
├── vite.config.ts      (viteSingleFile plugin)
├── server.ts           (createServer factory, registerAppTool, registerAppResource)
├── main.ts             (createMcpExpressApp, transport, shutdown)
├── mcp-app.html        (entry point for View)
└── src/
    └── mcp-app.ts      (App class, ontoolresult, callServerTool)

Connector registration (Claude.ai)

Claude.ai requires a public HTTPS URL. For local dev:

npx cloudflared tunnel --url http://localhost:3001
# Connector URL: https://<random>.trycloudflare.com/mcp

1. Settings → Connectors → Add custom connector
2. Paste your public URL
3. Enable per-conversation via "+" → Connectors in the chat composer

Team/Enterprise: Org owner adds in Admin Settings first.

Testing and debugging

MCP Inspector: npx @modelcontextprotocol/inspector — validate tools/resources outside Claude.

ext-apps basic-host: Clone github.com/modelcontextprotocol/ext-apps, run examples/basic-host — renders MCP App iframes with browser DevTools access.

Claude Desktop DevTools: Help → Troubleshooting → Enable Developer Mode → Cmd+Option+I. Navigate DOM tree to find the inner iframe.

Claude.ai web: No iframe DevTools access. Bundle everything into one file and test with the basic-host first.

Common mistakes