1---
2name: chatgpt-app-builder
3description: |
4  **MANDATORY for ALL MCP server work** - mcp-use framework best practices and patterns.
5 
6  **READ THIS FIRST** before any MCP server work, including:
7  - Creating new MCP servers
8  - Modifying existing MCP servers (adding/updating tools, resources, prompts, widgets)
9  - Debugging MCP server issues or errors
10  - Reviewing MCP server code for quality, security, or performance
11  - Answering questions about MCP development or mcp-use patterns
12  - Making ANY changes to server.tool(), server.resource(), server.prompt(), or widgets
13 
14  This skill contains critical architecture decisions, security patterns, and common pitfalls.
15  Always consult the relevant reference files BEFORE implementing MCP features.
16---
17 
18# IMPORTANT: How to Use This Skill
19 
20This file provides a NAVIGATION GUIDE ONLY. Before implementing any MCP server features, you MUST:
21 
221. Read this overview to understand which reference files are relevant
232. **ALWAYS read the specific reference file(s)** for the features you're implementing
243. Apply the detailed patterns from those files to your implementation
25 
26**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.
27 
28---
29 
30# MCP Server Best Practices
31 
32Comprehensive guide for building production-ready MCP servers with tools, resources, prompts, and widgets using mcp-use.
33 
34## ⚠️ FIRST: New Project or Existing Project?
35 
36**Before doing anything else, determine whether you are inside an existing mcp-use project.**
37 
38**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"`.
39 
40```
41├─ mcp-use project FOUND → Do NOT scaffold. You are already in a project.
42│  └─ Skip to "Quick Navigation" below to add features.
43│
44├─ NO mcp-use project (empty dir, unrelated project, or greenfield)
45│  └─ Scaffold first with npx create-mcp-use-app, then add features.
46│     See "Scaffolding a New Project" below.
47│
48└─ Inside an UNRELATED project (e.g. Next.js app) and user wants an MCP server
49   └─ Ask the user where to create it, then scaffold in that directory.
50      Do NOT scaffold inside an existing unrelated project root.
51```
52 
53**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.
54 
55---
56 
57### Scaffolding a New Project
58 
59```bash
60npx create-mcp-use-app my-server
61cd my-server
62npm run dev
63```
64 
65For full scaffolding details and CLI flags, see **[quickstart.md](references/foundations/quickstart.md)**.
66 
67---
68 
69## Quick Navigation
70 
71**Choose your path based on what you're building:**
72 
73### 🚀 Foundations
74**When:** ALWAYS read these first when starting MCP work in a new conversation. Reference later for architecture/concept clarification.
75 
761. **[concepts.md](references/foundations/concepts.md)** - MCP primitives (Tool, Resource, Prompt, Widget) and when to use each
772. **[architecture.md](references/foundations/architecture.md)** - Server structure (Hono-based), middleware system, server.use() vs server.app
783. **[quickstart.md](references/foundations/quickstart.md)** - Scaffolding, setup, and first tool example
794. **[deployment.md](references/foundations/deployment.md)** - Deploying to Manufact Cloud, self-hosting, Docker, managing deployments
80 
81Load these before diving into tools/resources/widgets sections.
82 
83---
84 
85### 🔐 Adding Authentication?
86**When:** Protecting your server with OAuth (Auth0, Better Auth, Clerk, WorkOS, Supabase, Keycloak, or any other provider)
87 
88- **[overview.md](references/authentication/overview.md)**
89  - When: First time adding auth, understanding `ctx.auth`, or choosing a provider / integration mode
90  - Covers: Remote auth vs OAuth proxy, `oauth` config, `ctx.auth` shape, provider comparison, common mistakes
91 
92- **[auth0.md](references/authentication/auth0.md)**
93  - When: Using Auth0 — DCR (Early Access) or a standard Regular Web App via `oauthProxy`
94  - Covers: Setup for both modes, `extraAuthorizeParams.audience`, permissions via `rfc9068_profile_authz`
95 
96- **[better-auth.md](references/authentication/better-auth.md)**
97  - When: Using Better Auth with the `@better-auth/oauth-provider` plugin (self-hosted OAuth 2.1)
98  - Covers: `oauthBetterAuthProvider`, auth URL / metadata routes, login and consent flows
99 
100- **[clerk.md](references/authentication/clerk.md)**
101  - When: Using Clerk (DCR-based OAuth)
102  - Covers: `oauthClerkProvider`, enabling DCR, Frontend API URL, organization context
103 
104- **[workos.md](references/authentication/workos.md)**
105  - When: Using WorkOS AuthKit (DCR only)
106  - Covers: Setup, env vars, roles/permissions, multi-tenant org filtering, WorkOS API calls
107 
108- **[supabase.md](references/authentication/supabase.md)**
109  - When: Using Supabase's OAuth 2.1 server
110  - Covers: Setup, publishable keys, ES256 vs HS256, hosting the consent UI, RLS-aware SDK calls
111 
112- **[keycloak.md](references/authentication/keycloak.md)**
113  - When: Using Keycloak via native DCR
114  - Covers: DCR trusted hosts + web origins, audience enforcement, realm vs resource roles, userinfo
115 
116- **[custom.md](references/authentication/custom.md)**
117  - When: Any other provider — DCR-capable via `oauthCustomProvider`, or pre-registered (Google, GitHub, Okta, Azure AD) via `oauthProxy`
118  - Covers: `oauthCustomProvider`, `oauthProxy` + `jwksVerifier`, provider examples, opaque-token verification
119 
120---
121 
122### 🔧 Building Server Backend (No UI)?
123**When:** Implementing MCP features (actions, data, templates). Read the specific file for the primitive you're building.
124 
125- **[tools.md](references/server/tools.md)**
126  - When: Creating backend actions the AI can call (send-email, fetch-data, create-user)
127  - Covers: Tool definition, schemas, annotations, context, error handling
128 
129- **[resources.md](references/server/resources.md)**
130  - When: Exposing read-only data clients can fetch (config, user profiles, documentation)
131  - Covers: Static resources, dynamic resources, parameterized resource templates, URI completion
132 
133- **[prompts.md](references/server/prompts.md)**
134  - When: Creating reusable message templates for AI interactions (code-review, summarize)
135  - Covers: Prompt definition, parameterization, argument completion, prompt best practices
136 
137- **[response-helpers.md](references/server/response-helpers.md)**
138  - When: Formatting responses from tools/resources (text, JSON, markdown, images, errors)
139  - Covers: `text()`, `object()`, `markdown()`, `image()`, `error()`, `mix()`
140 
141- **[proxy.md](references/server/proxy.md)**
142  - When: Composing multiple MCP servers into one unified aggregator server
143  - Covers: `server.proxy()`, config API, explicit sessions, sampling routing
144 
145- **[architecture.md](references/foundations/architecture.md)**
146  - When: Adding cross-cutting logic (logging, auth checks, rate limiting, tool filtering) that spans multiple tools/resources
147  - Covers: `server.use('mcp:...')` middleware, `MiddlewareContext` (method, params, auth, state), pattern matching, HTTP vs MCP middleware
148 
149---
150 
151### 🎨 Building Visual Widgets (Interactive UI)?
152**When:** Creating React-based visual interfaces for browsing, comparing, or selecting data
153 
154- **[basics.md](references/widgets/basics.md)**
155  - When: Creating your first widget or adding UI to an existing tool
156  - Covers: Widget setup, `useWidget()` hook, `isPending` checks, props handling
157 
158- **[state.md](references/widgets/state.md)**
159  - When: Managing UI state (selections, filters, tabs) within widgets
160  - Covers: `useState`, `setState`, state persistence, when to use tool vs widget state
161 
162- **[interactivity.md](references/widgets/interactivity.md)**
163  - When: Adding buttons, forms, or calling tools from within widgets
164  - Covers: `useCallTool()`, form handling, action buttons, optimistic updates
165 
166- **[ui-guidelines.md](references/widgets/ui-guidelines.md)**
167  - When: Styling widgets to support themes, responsive layouts, or accessibility
168  - Covers: `useWidgetTheme()`, light/dark mode, `autoSize`, layout patterns, CSS best practices
169 
170- **[advanced.md](references/widgets/advanced.md)**
171  - When: Building complex widgets with async data, error boundaries, or performance optimizations
172  - Covers: Loading states, error handling, memoization, code splitting
173 
174- **[model-context.md](references/widgets/model-context.md)**
175  - When: Keeping the AI model aware of what the user is currently seeing (active tab, hovered item, selected product) without requiring tool calls
176  - Covers: `<ModelContext>` component, `modelContext.set/remove` imperative API, nesting, tree serialization, lifecycle rules
177- **[files.md](references/widgets/files.md)**
178  - When: Uploading or downloading files from within a widget (ChatGPT Apps SDK only)
179  - Covers: `useFiles()` hook, `isSupported` guard, model visibility (`modelVisible`), storing `fileId`, temporary download URLs
180 
181---
182 
183### 📚 Need Complete Examples?
184**When:** You want to see full implementations of common use cases
185 
186- **[common-patterns.md](references/patterns/common-patterns.md)**
187  - End-to-end examples: weather app, todo list, recipe browser
188  - Shows: Server code + widget code + best practices in context
189 
190---
191 
192## Decision Tree
193 
194```
195What do you need?
196 
197├─ New project from scratch
198│  └─> quickstart.md (scaffolding + setup)
199│
200├─ OAuth / user authentication
201│  └─> authentication/overview.md → provider-specific guide
202│
203├─ Simple backend action (no UI)
204│  └─> Use Tool: server/tools.md
205│
206├─ Read-only data for clients
207│  └─> Use Resource: server/resources.md
208│
209├─ Reusable prompt template
210│  └─> Use Prompt: server/prompts.md
211│
212├─ Cross-cutting logic (logging, auth checks, rate limiting, tool filtering)
213│  └─> Use Middleware: architecture.md#mcp-middleware
214│
215├─ Visual/interactive UI
216│  └─> Use Widget: widgets/basics.md
217│
218├─ Keep model aware of what user is seeing in widget
219│  └─> widgets/model-context.md
220├─ Upload/download files in a widget
221│  └─> widgets/files.md (ChatGPT Apps SDK only)
222│
223└─ Deploy to production
224   └─> deployment.md (cloud deploy, self-hosting, Docker)
225```
226 
227---
228 
229## Core Principles
230 
2311. **Tools for actions** - Backend operations with input/output
2322. **Resources for data** - Read-only data clients can fetch
2333. **Prompts for templates** - Reusable message templates
2344. **Widgets for UI** - Visual interfaces when helpful
2355. **Mock data first** - Prototype quickly, connect APIs later
236 
237---
238 
239## ❌ Common Mistakes
240 
241Avoid these anti-patterns found in production MCP servers:
242 
243### Tool Definition
244- ❌ Returning raw objects instead of using response helpers
245  - ✅ Use `text()`, `object()`, `widget()`, `error()` helpers
246- ❌ Skipping Zod schema `.describe()` on every field
247  - ✅ Add descriptions to all schema fields for better AI understanding
248- ❌ No input validation or sanitization
249  - ✅ Validate inputs with Zod, sanitize user-provided data
250- ❌ Throwing errors instead of returning `error()` helper
251  - ✅ Use `error("message")` for graceful error responses
252 
253### Widget Development
254- ❌ Accessing `props` without checking `isPending`
255  - ✅ Always check `if (isPending) return <Loading/>`
256- ❌ Widget handles server state (filters, selections)
257  - ✅ Widgets manage their own UI state with `useState`
258- ❌ Missing `McpUseProvider` wrapper or `autoSize`
259  - ✅ Wrap root component: `<McpUseProvider autoSize>`
260- ❌ Inline styles without theme awareness
261  - ✅ Use `useWidgetTheme()` for light/dark mode support
262 
263### Security & Production
264- ❌ Hardcoded API keys or secrets in code
265  - ✅ Use `process.env.API_KEY`, document in `.env.example`
266- ❌ No error handling in tool handlers
267  - ✅ Wrap in try/catch, return `error()` on failure
268- ❌ Expensive operations without caching
269  - ✅ Cache API calls, computations with TTL
270- ❌ Missing CORS configuration
271  - ✅ Configure CORS for production deployments
272 
273---
274 
275## 🔒 Golden Rules
276 
277**Opinionated architectural guidelines:**
278 
279### 1. One Tool = One Capability
280Split broad actions into focused tools:
281- ❌ `manage-users` (too vague)
282- ✅ `create-user`, `delete-user`, `list-users`
283 
284### 2. Return Complete Data Upfront
285Tool calls are expensive. Avoid lazy-loading:
286- ❌ `list-products` + `get-product-details` (2 calls)
287- ✅ `list-products` returns full data including details
288 
289### 3. Widgets Own Their State
290UI state lives in the widget, not in separate tools:
291- ❌ `select-item` tool, `set-filter` tool
292- ✅ Widget manages with `useState` or `setState`
293 
294### 4. `exposeAsTool` Defaults to `false`
295Widgets are registered as resources only by default. Use a custom tool (recommended) or set `exposeAsTool: true` to expose a widget to the model:
296 
297```typescript
298// ✅ ALL 4 STEPS REQUIRED for proper type inference:
299 
300// Step 1: Define schema separately
301const propsSchema = z.object({
302  title: z.string(),
303  items: z.array(z.string())
304});
305 
306// Step 2: Reference schema variable in metadata
307export const widgetMetadata: WidgetMetadata = {
308  description: "...",
309  props: propsSchema,  // ← NOT inline z.object()
310  exposeAsTool: false
311};
312 
313// Step 3: Infer Props type from schema variable
314type Props = z.infer<typeof propsSchema>;
315 
316// Step 4: Use typed Props with useWidget
317export default function MyWidget() {
318  const { props, isPending } = useWidget<Props>();  // ← Add <Props>
319  // ...
320}
321```
322 
323⚠️ **Common mistake:** Only doing steps 1-2 but skipping 3-4 (loses type safety)
324 
325### 5. Validate at Boundaries Only
326- Trust internal code and framework guarantees
327- Validate user input, external API responses
328- Don't add error handling for scenarios that can't happen
329 
330### 6. Prefer Widgets for Browsing/Comparing
331When in doubt, add a widget. Visual UI improves:
332- Browsing multiple items
333- Comparing data side-by-side
334- Interactive selection workflows
335 
336---
337 
338## Quick Reference
339 
340### Minimal Server
341```typescript
342import { MCPServer, text } from "mcp-use/server";
343import { z } from "zod";
344 
345const server = new MCPServer({
346  name: "my-server",
347  title: "My Server",
348  version: "1.0.0"
349});
350 
351server.tool(
352  {
353    name: "greet",
354    description: "Greet a user",
355    schema: z.object({ name: z.string().describe("User's name") })
356  },
357  async ({ name }) => text("Hello " + name + "!"),
358);
359 
360server.listen();
361```
362 
363---
364 
365## Response Helpers
366 
367| Helper | Use When | Example |
368|--------|----------|---------|
369| `text()` | Simple string response | `text("Success!")` |
370| `object()` | Structured data | `object({ status: "ok" })` |
371| `markdown()` | Formatted text | `markdown("# Title\nContent")` |
372| `widget()` | Visual UI | `widget({ props: {...}, output: text(...) })` |
373| `mix()` | Multiple contents | `mix(text("Hi"), image(url))` |
374| `error()` | Error responses | `error("Failed to fetch data")` |
375| `resource()` | Embed resource refs | `resource("docs://guide", "text/markdown")` |
376 
377**Server methods:**
378- `server.tool()` - Define executable tool
379- `server.resource()` - Define static/dynamic resource
380- `server.resourceTemplate()` - Define parameterized resource
381- `server.prompt()` - Define prompt template
382- `server.proxy()` - Compose/Proxy multiple MCP servers
383- `server.uiResource()` - Define widget resource
384- `server.listen()` - Start server
385- `server.use('mcp:tools/call', fn)` - MCP middleware (tools, resources, prompts, list ops)
386- `server.use('mcp:*', fn)` - Catch-all MCP middleware
387- `server.use(fn)` - HTTP middleware (Hono)
388