MCP App Template

Official starter for building MCP Apps on deco — interactive UIs powered by the Model Context Protocol.

Quick Start

# Clone the template
git clone https://github.com/decocms/mcp-app.git my-mcp-app
cd my-mcp-app

# Install dependencies
bun install

# Start development
bun run dev

Project Structure

├── api/                        # MCP server (platform-agnostic)
│   ├── app.ts                  # App core — tools, resources, middleware
│   ├── main.bun.ts             # Bun entrypoint (local dev)
│   ├── tools/
│   │   ├── index.ts            # Tool registry
│   │   └── hello.ts            # Example tool (hello_world)
│   ├── resources/
│   │   └── hello.ts            # MCP App resource (serves HTML)
│   └── types/
│       └── env.ts              # StateSchema + Env type
├── web/                        # React UI (MCP App)
│   ├── tools/                  # One folder per tool UI (folder-based routing)
│   │   └── hello/              # hello_world tool UI
│   │       ├── main.tsx        # React entry point
│   │       ├── bridge.ts       # MCP App SDK integration
│   │       ├── context.tsx     # React context for MCP state
│   │       ├── router.tsx      # TanStack Router with UI
│   │       └── types.ts        # UI state types
│   ├── entry.tsx               # Build entry (imports @tool/main.tsx)
│   ├── components/ui/          # shadcn/ui components
│   ├── lib/utils.ts            # cn() helper
│   └── globals.css             # Tailwind base styles
├── index.html                  # Single Vite entry (shared by all tools)
├── package.json
├── tsconfig.json
├── biome.json
├── vite.config.ts
├── components.json             # shadcn/ui config
├── app.json                    # Deco mesh config
└── .mcp.json                   # Local MCP server config

Development

# Run API server + web build concurrently
bun run dev

# API server only (port 3001)
bun run dev:api

# Web build only (watch mode)
bun run dev:web

Connecting to deco Studio

To test your MCP App in deco Studio, expose your local server through a tunnel:

bun start
# Tunnel started -> 🌐 Preview: https://<your-id>.deco.host

Then connect in Studio using the MCP URL:

https://<your-id>.deco.host/api/mcp

Adding a New Tool with UI

Each tool UI lives in web/tools/<name>/. The TOOL env var tells Vite which folder to build — one build per tool, output as dist/client/<name>.html.

1. Create the tool — api/tools/my-tool.ts using createTool
2. Register it — add to the tools array in api/tools/index.ts
3. Create the UI — web/tools/my-tool/ with main.tsx, bridge.ts, context.tsx, router.tsx, types.ts
4. Create the resource — api/resources/my-tool.ts serving dist/client/my-tool.html
5. Update build scripts:

   "build:web": "TOOL=hello vite build && TOOL=my-tool vite build",
   "dev:web": "concurrently \"TOOL=hello vite build --watch\" \"TOOL=my-tool vite build --watch\""
   

How the Tool Router Works

TOOL=hello vite build
  → resolves @tool/* → web/tools/hello/*
  → index.html imports web/entry.tsx imports @tool/main.tsx
  → outputs dist/client/hello.html (single-file bundle)

Tech Stack

• Runtime: Bun (default), deployable to any Web Standard runtime
• Server: @decocms/runtime MCP server
• UI: React 19 + TanStack Router (hash-based) + TanStack Query
• Styling: Tailwind CSS v4 + shadcn/ui
• MCP Apps: @modelcontextprotocol/ext-apps SDK
• Build: Vite + vite-plugin-singlefile
• Linting: Biome

How It Works

1. The app core (api/app.ts) defines tools, resources, and middleware as a platform-agnostic fetch handler
2. A platform entrypoint (api/main.bun.ts) starts the server using the platform's API
3. Tools perform actions and can link to a UI via _meta.ui.resourceUri
4. Resources serve single-file HTML bundles with mimeType: "text/html;profile=mcp-app"
5. The MCP App UI connects to the host via @modelcontextprotocol/ext-apps, receives tool input/results, and renders an interactive display
6. Vite builds each tool UI into a self-contained HTML file (CSS + JS inlined) using the TOOL env var to select which web/tools/<name>/ folder to bundle

Deployment

Multi-Platform

The app uses a factory pattern that separates business logic (api/app.ts) from platform wiring. To deploy to a new platform, add a thin entrypoint file — see the add-deploy-target skill for step-by-step instructions.

Supported targets out of the box:

• Bun — api/main.bun.ts (default, used for local dev)

Easy to add:

• Cloudflare Workers — ~5 lines + wrangler.toml
• Deno — ~5 lines
• Node.js — ~5 lines + @hono/node-server
• AWS Lambda — ~5 lines + hono/aws-lambda

Publish to deco

1. Update app.json with your app's name, description, and connection URL
2. Push to your repository — CI will validate the build
3. Follow deco mesh publishing instructions to deploy

CI

GitHub Actions runs on every push and pull request:

• bun run ci:check — Biome lint + format check
• bun run check — TypeScript type checking
• bun test — Unit tests
• bun run build — Production build