mcp-apps-builder

SKILL.md

IMPORTANT: How to Use This Skill

This file provides a NAVIGATION GUIDE ONLY. Before implementing any MCP server features, you MUST:

Read this overview to understand which reference files are relevant

ALWAYS read the specific reference file(s) for the features you're implementing

Apply the detailed patterns from those files to your implementation

Do NOT rely solely on the quick reference examples in this file - they are minimal examples only. The reference files contain critical best practices, security considerations, and advanced patterns.

MCP Server Best Practices

Comprehensive guide for building production-ready MCP servers with tools, resources, prompts, and widgets using mcp-use.

⚠️ FIRST: New Project or Existing Project?

Before doing anything else, determine whether you are inside an existing mcp-use project.
Detection: Check the workspace for a package.json that lists "mcp-use" as a dependency, OR any .ts file that imports from "mcp-use/server".

├─ mcp-use project FOUND → Do NOT scaffold. You are already in a project.
│  └─ Skip to "Quick Navigation" below to add features.
│
├─ NO mcp-use project (empty dir, unrelated project, or greenfield)
│  └─ Scaffold first with npx create-mcp-use-app, then add features.
│     See "Scaffolding a New Project" below.
│
└─ Inside an UNRELATED project (e.g. Next.js app) and user wants an MCP server
   └─ Ask the user where to create it, then scaffold in that directory.
      Do NOT scaffold inside an existing unrelated project root.

NEVER manually create MCPServer boilerplate, package.json, or project structure by hand. The CLI sets up TypeScript config, dev scripts, inspector integration, hot reload, and widget compilation that are difficult to replicate manually.

Scaffolding a New Project

npx create-mcp-use-app my-server
cd my-server
npm run dev

For full scaffolding details and CLI flags, see quickstart.md.

Quick Navigation

Choose your path based on what you're building:

🚀 Foundations

When: ALWAYS read these first when starting MCP work in a new conversation. Reference later for architecture/concept clarification.

concepts.md - MCP primitives (Tool, Resource, Prompt, Widget) and when to use each

architecture.md - Server structure (Hono-based), middleware system, server.use() vs server.app

quickstart.md - Scaffolding, setup, and first tool example

deployment.md - Deploying to Manufact Cloud, self-hosting, Docker, managing deployments

Load these before diving into tools/resources/widgets sections.

🔐 Adding Authentication?

When: Protecting your server with OAuth (Auth0, Better Auth, Clerk, WorkOS, Supabase, Keycloak, or any other provider)

overview.md

When: First time adding auth, understanding ctx.auth, or choosing a provider / integration mode

Covers: Remote auth vs OAuth proxy, oauth config, ctx.auth shape, provider comparison, common mistakes

auth0.md

When: Using Auth0 — DCR (Early Access) or a standard Regular Web App via oauthProxy

Covers: Setup for both modes, extraAuthorizeParams.audience, permissions via rfc9068_profile_authz

better-auth.md

When: Using Better Auth with the @better-auth/oauth-provider plugin (self-hosted OAuth 2.1)

Covers: oauthBetterAuthProvider, auth URL / metadata routes, login and consent flows

clerk.md

When: Using Clerk (DCR-based OAuth)

Covers: oauthClerkProvider, enabling DCR, Frontend API URL, organization context

workos.md

When: Using WorkOS AuthKit (DCR only)

Covers: Setup, env vars, roles/permissions, multi-tenant org filtering, WorkOS API calls

supabase.md

When: Using Supabase's OAuth 2.1 server

Covers: Setup, publishable keys, ES256 vs HS256, hosting the consent UI, RLS-aware SDK calls

keycloak.md

When: Using Keycloak via native DCR

Covers: DCR trusted hosts + web origins, audience enforcement, realm vs resource roles, userinfo

custom.md

When: Any other provider — DCR-capable via oauthCustomProvider, or pre-registered (Google, GitHub, Okta, Azure AD) via oauthProxy

Covers: oauthCustomProvider, oauthProxy + jwksVerifier, provider examples, opaque-token verification

🔧 Building Server Backend (No UI)?

When: Implementing MCP features (actions, data, templates). Read the specific file for the primitive you're building.

tools.md

When: Creating backend actions the AI can call (send-email, fetch-data, create-user)

Covers: Tool definition, schemas, annotations, context, error handling

resources.md

When: Exposing read-only data clients can fetch (config, user profiles, documentation)

Covers: Static resources, dynamic resources, parameterized resource templates, URI completion

prompts.md

When: Creating reusable message templates for AI interactions (code-review, summarize)

Covers: Prompt definition, parameterization, argument completion, prompt best practices

response-helpers.md

When: Formatting responses from tools/resources (text, JSON, markdown, images, errors)

Covers: text(), object(), markdown(), image(), error(), mix()

proxy.md

When: Composing multiple MCP servers into one unified aggregator server

Covers: server.proxy(), config API, explicit sessions, sampling routing

architecture.md

When: Adding cross-cutting logic (logging, auth checks, rate limiting, tool filtering) that spans multiple tools/resources

Covers: server.use('mcp:...') middleware, MiddlewareContext (method, params, auth, state), pattern matching, HTTP vs MCP middleware

🎨 Building Visual Widgets (Interactive UI)?

When: Creating React-based visual interfaces for browsing, comparing, or selecting data

basics.md

When: Creating your first widget or adding UI to an existing tool

Covers: Widget setup, useWidget() hook, isPending checks, props handling

state.md

When: Managing UI state (selections, filters, tabs) within widgets

Covers: useState, setState, state persistence, when to use tool vs widget state

interactivity.md

When: Adding buttons, forms, or calling tools from within widgets

Covers: useCallTool(), form handling, action buttons, optimistic updates

ui-guidelines.md

When: Styling widgets to support themes, responsive layouts, or accessibility

Covers: useWidgetTheme(), light/dark mode, autoSize, layout patterns, CSS best practices

advanced.md

When: Building complex widgets with async data, error boundaries, or performance optimizations

Covers: Loading states, error handling, memoization, code splitting

model-context.md

When: Keeping the AI model aware of what the user is currently seeing (active tab, hovered item, selected product) without requiring tool calls

Covers: <ModelContext> component, modelContext.set/remove imperative API, nesting, tree serialization, lifecycle rules

files.md

When: Uploading or downloading files from within a widget (ChatGPT Apps SDK only)

Covers: useFiles() hook, isSupported guard, model visibility (modelVisible), storing fileId, temporary download URLs

📚 Need Complete Examples?

When: You want to see full implementations of common use cases

common-patterns.md

End-to-end examples: weather app, todo list, recipe browser

Shows: Server code + widget code + best practices in context

🔁 Testing from the Terminal (Agent Feedback Loops)

When: You want to verify a tool or widget without the inspector UI — the canonical flow for AI agents iterating on MCP servers.

mcp-use client — drives MCP servers from the terminal. Auto-runs OAuth on 401, persists saved servers under a short name, and one-shot subcommands exit cleanly so they're safe to spawn from harnesses.

npx mcp-use client connect dev http://localhost:3000/mcp
npx mcp-use client dev tools list
npx mcp-use client dev tools call get-weather city=Tokyo --screenshot

Every per-server command takes the saved name as its first positional arg (mcp-use client <name> <scope> <action>) — there is no "active session". Args use key=value (with key:='<json>' for nested values) or a single JSON object. When a tool renders a widget, pass --screenshot to also save a PNG (./<view>-<timestamp>.png by default, or override with --screenshot-output <path>).

mcp-use client screenshot — headless render of a widget tool to a PNG. Use this when you want to visually verify a widget change without opening the inspector, especially in loops where you call a tool, screenshot, eyeball the output, and edit. Two forms:

# Saved-server form — reuses the auth from `mcp-use client connect`
npx mcp-use client dev screenshot --tool get-weather city=Tokyo \
  --width 800 --height 600 --theme light \
  --output ./weather.png

# Ad-hoc form — connect inline (use -H for headers on authenticated servers)
npx mcp-use client screenshot --mcp http://localhost:3000/mcp \
  --tool get-weather city=Tokyo

Add --device-scale-factor 2 for Retina output, or --cdp-url <ws> plus --inspector <publicly-reachable-url> to drive a remote Chromium (e.g. Notte) from a sandbox without a local Chrome install.

Both commands are documented in full at docs/typescript/client/cli.

Decision Tree

What do you need?

├─ New project from scratch
│  └─> quickstart.md (scaffolding + setup)
│
├─ OAuth / user authentication
│  └─> authentication/overview.md → provider-specific guide
│
├─ Simple backend action (no UI)
│  └─> Use Tool: server/tools.md
│
├─ Read-only data for clients
│  └─> Use Resource: server/resources.md
│
├─ Reusable prompt template
│  └─> Use Prompt: server/prompts.md
│
├─ Cross-cutting logic (logging, auth checks, rate limiting, tool filtering)
│  └─> Use Middleware: architecture.md#mcp-middleware
│
├─ Visual/interactive UI
│  └─> Use Widget: widgets/basics.md
│
├─ Keep model aware of what user is seeing in widget
│  └─> widgets/model-context.md
├─ Upload/download files in a widget
│  └─> widgets/files.md (ChatGPT Apps SDK only)
│
├─ Verify a tool or widget from the terminal (agent feedback loop)
│  └─> See "Testing from the Terminal" above — `mcp-use client` for tool runs,
│      `mcp-use client <server> screenshot --tool <tool>` for headless widget PNGs
│
└─ Deploy to production
   └─> deployment.md (cloud deploy, self-hosting, Docker)

Core Principles

Tools for actions - Backend operations with input/output

Resources for data - Read-only data clients can fetch

Prompts for templates - Reusable message templates

Widgets for UI - Visual interfaces when helpful

Mock data first - Prototype quickly, connect APIs later

❌ Common Mistakes

Avoid these anti-patterns found in production MCP servers:

Tool Definition

❌ Returning raw objects instead of using response helpers

✅ Use text(), object(), widget(), error() helpers

❌ Skipping Zod schema .describe() on every field

✅ Add descriptions to all schema fields for better AI understanding

❌ No input validation or sanitization

✅ Validate inputs with Zod, sanitize user-provided data

❌ Throwing errors instead of returning error() helper

✅ Use error("message") for graceful error responses

Widget Development

❌ Accessing props without checking isPending

✅ Always check if (isPending) return <Loading/>

❌ Widget handles server state (filters, selections)

✅ Widgets manage their own UI state with useState

❌ Missing McpUseProvider wrapper or autoSize

✅ Wrap root component: <McpUseProvider autoSize>

❌ Inline styles without theme awareness

✅ Use useWidgetTheme() for light/dark mode support

Security & Production

❌ Hardcoded API keys or secrets in code

✅ Use process.env.API_KEY, document in .env.example

❌ No error handling in tool handlers

✅ Wrap in try/catch, return error() on failure

❌ Expensive operations without caching

✅ Cache API calls, computations with TTL

❌ Missing CORS configuration

✅ Configure CORS for production deployments

🔒 Golden Rules

Opinionated architectural guidelines:

1. One Tool = One Capability

Split broad actions into focused tools:

❌ manage-users (too vague)

✅ create-user, delete-user, list-users

2. Return Complete Data Upfront

Tool calls are expensive. Avoid lazy-loading:

❌ list-products + get-product-details (2 calls)

✅ list-products returns full data including details

3. Widgets Own Their State

UI state lives in the widget, not in separate tools:

❌ select-item tool, set-filter tool

✅ Widget manages with useState or setState

4. exposeAsTool Defaults to false

Widgets are registered as resources only by default. Use a custom tool (recommended) or set exposeAsTool: true to expose a widget to the model:

// ✅ ALL 4 STEPS REQUIRED for proper type inference:

// Step 1: Define schema separately
const propsSchema = z.object({
  title: z.string(),
  items: z.array(z.string())
});

// Step 2: Reference schema variable in metadata
export const widgetMetadata: WidgetMetadata = {
  description: "...",
  props: propsSchema,  // ← NOT inline z.object()
  exposeAsTool: false
};

// Step 3: Infer Props type from schema variable
type Props = z.infer<typeof propsSchema>;

// Step 4: Use typed Props with useWidget
export default function MyWidget() {
  const { props, isPending } = useWidget<Props>();  // ← Add <Props>
  // ...
}

⚠️ Common mistake: Only doing steps 1-2 but skipping 3-4 (loses type safety)

5. Validate at Boundaries Only

Trust internal code and framework guarantees

Validate user input, external API responses

Don't add error handling for scenarios that can't happen

6. Prefer Widgets for Browsing/Comparing

When in doubt, add a widget. Visual UI improves:

Browsing multiple items

Comparing data side-by-side

Interactive selection workflows

Quick Reference

Minimal Server

import { MCPServer, text } from "mcp-use/server";
import { z } from "zod";

const server = new MCPServer({
  name: "my-server",
  title: "My Server",
  version: "1.0.0"
});

server.tool(
  {
    name: "greet",
    description: "Greet a user",
    schema: z.object({ name: z.string().describe("User's name") })
  },
  async ({ name }) => text("Hello " + name + "!"),
);

server.listen();

Response Helpers

Helper
Use When
Example

text()
Simple string response
text("Success!")

object()
Structured data
object({ status: "ok" })

markdown()
Formatted text
markdown("# Title\nContent")

widget()
Visual UI
widget({ props: {...}, output: text(...) })

mix()
Multiple contents
mix(text("Hi"), image(url))

error()
Error responses
error("Failed to fetch data")

resource()
Embed resource refs
resource("docs://guide", "text/markdown")

Server methods:

server.tool() - Define executable tool

server.resource() - Define static/dynamic resource

server.resourceTemplate() - Define parameterized resource

server.prompt() - Define prompt template

server.proxy() - Compose/Proxy multiple MCP servers

server.uiResource() - Define widget resource

server.listen() - Start server

server.use('mcp:tools/call', fn) - MCP middleware (tools, resources, prompts, list ops)

server.use('mcp:*', fn) - Catch-all MCP middleware

server.use(fn) - HTTP middleware (Hono)