Build ChatGPT apps with interactive widgets using mcp-use and OpenAI Apps SDK. Use when creating ChatGPT apps, building MCP servers with widgets, defining React widgets, working with Apps SDK, or when user mentions ChatGPT widgets, mcp-use widgets, or Apps SDK development.
npxskills add mcp-use/mcp-use--skill chatgpt-app-builderLoading…
This file provides a NAVIGATION GUIDE ONLY. Before implementing any MCP server features, you MUST:
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.
Comprehensive guide for building production-ready MCP servers with tools, resources, prompts, and widgets using mcp-use.
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.
npx create-mcp-use-app my-server
cd my-server
npm run dev
For full scaffolding details and CLI flags, see quickstart.md.
Choose your path based on what you're building:
When: ALWAYS read these first when starting MCP work in a new conversation. Reference later for architecture/concept clarification.
Load these before diving into tools/resources/widgets sections.
When: Protecting your server with OAuth (Auth0, Better Auth, Clerk, WorkOS, Supabase, Keycloak, or any other provider)
ctx.auth, or choosing a provider / integration modeoauth config, ctx.auth shape, provider comparison, common mistakesoauthProxyextraAuthorizeParams.audience, permissions via rfc9068_profile_authz@better-auth/oauth-provider plugin (self-hosted OAuth 2.1)oauthBetterAuthProvider, auth URL / metadata routes, login and consent flowsoauthClerkProvider, enabling DCR, Frontend API URL, organization contextoauthCustomProvider, or pre-registered (Google, GitHub, Okta, Azure AD) via oauthProxyoauthCustomProvider, oauthProxy + jwksVerifier, provider examples, opaque-token verificationWhen: Implementing MCP features (actions, data, templates). Read the specific file for the primitive you're building.
text(), object(), markdown(), image(), error(), mix()server.proxy(), config API, explicit sessions, sampling routingserver.use('mcp:...') middleware, MiddlewareContext (method, params, auth, state), pattern matching, HTTP vs MCP middlewareWhen: Creating React-based visual interfaces for browsing, comparing, or selecting data
useWidget() hook, isPending checks, props handlinguseState, setState, state persistence, when to use tool vs widget stateuseCallTool(), form handling, action buttons, optimistic updatesuseWidgetTheme(), light/dark mode, autoSize, layout patterns, CSS best practices<ModelContext> component, modelContext.set/remove imperative API, nesting, tree serialization, lifecycle rulesuseFiles() hook, isSupported guard, model visibility (modelVisible), storing fileId, temporary download URLsWhen: You want to see full implementations of common use cases
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.
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)
Avoid these anti-patterns found in production MCP servers:
text(), object(), widget(), error() helpers.describe() on every field
error() helper
error("message") for graceful error responsesprops without checking isPending
if (isPending) return <Loading/>useStateMcpUseProvider wrapper or autoSize
<McpUseProvider autoSize>useWidgetTheme() for light/dark mode supportprocess.env.API_KEY, document in .env.exampleerror() on failureOpinionated architectural guidelines:
Split broad actions into focused tools:
manage-users (too vague)create-user, delete-user, list-usersTool calls are expensive. Avoid lazy-loading:
list-products + get-product-details (2 calls)list-products returns full data including detailsUI state lives in the widget, not in separate tools:
select-item tool, set-filter tooluseState or setStateexposeAsTool Defaults to falseWidgets 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)
When in doubt, add a widget. Visual UI improves:
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();
| 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 toolserver.resource() - Define static/dynamic resourceserver.resourceTemplate() - Define parameterized resourceserver.prompt() - Define prompt templateserver.proxy() - Compose/Proxy multiple MCP serversserver.uiResource() - Define widget resourceserver.listen() - Start serverserver.use('mcp:tools/call', fn) - MCP middleware (tools, resources, prompts, list ops)server.use('mcp:*', fn) - Catch-all MCP middlewareserver.use(fn) - HTTP middleware (Hono)
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).