1---
2name: mcp-apps-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, 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- **[workos.md](references/authentication/workos.md)**
101  - When: Using WorkOS AuthKit (DCR only)
102  - Covers: Setup, env vars, roles/permissions, multi-tenant org filtering, WorkOS API calls
103 
104- **[supabase.md](references/authentication/supabase.md)**
105  - When: Using Supabase's OAuth 2.1 server
106  - Covers: Setup, publishable keys, ES256 vs HS256, hosting the consent UI, RLS-aware SDK calls
107 
108- **[keycloak.md](references/authentication/keycloak.md)**
109  - When: Using Keycloak via native DCR
110  - Covers: DCR trusted hosts + web origins, audience enforcement, realm vs resource roles, userinfo
111 
112- **[custom.md](references/authentication/custom.md)**
113  - When: Any other provider — DCR-capable via `oauthCustomProvider`, or pre-registered (Google, GitHub, Okta, Azure AD) via `oauthProxy`
114  - Covers: `oauthCustomProvider`, `oauthProxy` + `jwksVerifier`, provider examples, opaque-token verification
115 
116---
117 
118### 🔧 Building Server Backend (No UI)?
119**When:** Implementing MCP features (actions, data, templates). Read the specific file for the primitive you're building.
120 
121- **[tools.md](references/server/tools.md)**
122  - When: Creating backend actions the AI can call (send-email, fetch-data, create-user)
123  - Covers: Tool definition, schemas, annotations, context, error handling
124 
125- **[resources.md](references/server/resources.md)**
126  - When: Exposing read-only data clients can fetch (config, user profiles, documentation)
127  - Covers: Static resources, dynamic resources, parameterized resource templates, URI completion
128 
129- **[prompts.md](references/server/prompts.md)**
130  - When: Creating reusable message templates for AI interactions (code-review, summarize)
131  - Covers: Prompt definition, parameterization, argument completion, prompt best practices
132 
133- **[response-helpers.md](references/server/response-helpers.md)**
134  - When: Formatting responses from tools/resources (text, JSON, markdown, images, errors)
135  - Covers: `text()`, `object()`, `markdown()`, `image()`, `error()`, `mix()`
136 
137- **[proxy.md](references/server/proxy.md)**
138  - When: Composing multiple MCP servers into one unified aggregator server
139  - Covers: `server.proxy()`, config API, explicit sessions, sampling routing
140 
141- **[architecture.md](references/foundations/architecture.md)**
142  - When: Adding cross-cutting logic (logging, auth checks, rate limiting, tool filtering) that spans multiple tools/resources
143  - Covers: `server.use('mcp:...')` middleware, `MiddlewareContext` (method, params, auth, state), pattern matching, HTTP vs MCP middleware
144 
145---
146 
147### 🎨 Building Visual Widgets (Interactive UI)?
148**When:** Creating React-based visual interfaces for browsing, comparing, or selecting data
149 
150- **[basics.md](references/widgets/basics.md)**
151  - When: Creating your first widget or adding UI to an existing tool
152  - Covers: Widget setup, `useWidget()` hook, `isPending` checks, props handling
153 
154- **[state.md](references/widgets/state.md)**
155  - When: Managing UI state (selections, filters, tabs) within widgets
156  - Covers: `useState`, `setState`, state persistence, when to use tool vs widget state
157 
158- **[interactivity.md](references/widgets/interactivity.md)**
159  - When: Adding buttons, forms, or calling tools from within widgets
160  - Covers: `useCallTool()`, form handling, action buttons, optimistic updates
161 
162- **[ui-guidelines.md](references/widgets/ui-guidelines.md)**
163  - When: Styling widgets to support themes, responsive layouts, or accessibility
164  - Covers: `useWidgetTheme()`, light/dark mode, `autoSize`, layout patterns, CSS best practices
165 
166- **[advanced.md](references/widgets/advanced.md)**
167  - When: Building complex widgets with async data, error boundaries, or performance optimizations
168  - Covers: Loading states, error handling, memoization, code splitting
169 
170- **[model-context.md](references/widgets/model-context.md)**
171  - When: Keeping the AI model aware of what the user is currently seeing (active tab, hovered item, selected product) without requiring tool calls
172  - Covers: `<ModelContext>` component, `modelContext.set/remove` imperative API, nesting, tree serialization, lifecycle rules
173- **[files.md](references/widgets/files.md)**
174  - When: Uploading or downloading files from within a widget (ChatGPT Apps SDK only)
175  - Covers: `useFiles()` hook, `isSupported` guard, model visibility (`modelVisible`), storing `fileId`, temporary download URLs
176 
177---
178 
179### 📚 Need Complete Examples?
180**When:** You want to see full implementations of common use cases
181 
182- **[common-patterns.md](references/patterns/common-patterns.md)**
183  - End-to-end examples: weather app, todo list, recipe browser
184  - Shows: Server code + widget code + best practices in context
185 
186---
187 
188## Decision Tree
189 
190```
191What do you need?
192 
193├─ New project from scratch
194│  └─> quickstart.md (scaffolding + setup)
195│
196├─ OAuth / user authentication
197│  └─> authentication/overview.md → provider-specific guide
198│
199├─ Simple backend action (no UI)
200│  └─> Use Tool: server/tools.md
201│
202├─ Read-only data for clients
203│  └─> Use Resource: server/resources.md
204│
205├─ Reusable prompt template
206│  └─> Use Prompt: server/prompts.md
207│
208├─ Cross-cutting logic (logging, auth checks, rate limiting, tool filtering)
209│  └─> Use Middleware: architecture.md#mcp-middleware
210│
211├─ Visual/interactive UI
212│  └─> Use Widget: widgets/basics.md
213│
214├─ Keep model aware of what user is seeing in widget
215│  └─> widgets/model-context.md
216├─ Upload/download files in a widget
217│  └─> widgets/files.md (ChatGPT Apps SDK only)
218│
219└─ Deploy to production
220   └─> deployment.md (cloud deploy, self-hosting, Docker)
221```
222 
223---
224 
225## Core Principles
226 
2271. **Tools for actions** - Backend operations with input/output
2282. **Resources for data** - Read-only data clients can fetch
2293. **Prompts for templates** - Reusable message templates
2304. **Widgets for UI** - Visual interfaces when helpful
2315. **Mock data first** - Prototype quickly, connect APIs later
232 
233---
234 
235## ❌ Common Mistakes
236 
237Avoid these anti-patterns found in production MCP servers:
238 
239### Tool Definition
240- ❌ Returning raw objects instead of using response helpers
241  - ✅ Use `text()`, `object()`, `widget()`, `error()` helpers
242- ❌ Skipping Zod schema `.describe()` on every field
243  - ✅ Add descriptions to all schema fields for better AI understanding
244- ❌ No input validation or sanitization
245  - ✅ Validate inputs with Zod, sanitize user-provided data
246- ❌ Throwing errors instead of returning `error()` helper
247  - ✅ Use `error("message")` for graceful error responses
248 
249### Widget Development
250- ❌ Accessing `props` without checking `isPending`
251  - ✅ Always check `if (isPending) return <Loading/>`
252- ❌ Widget handles server state (filters, selections)
253  - ✅ Widgets manage their own UI state with `useState`
254- ❌ Missing `McpUseProvider` wrapper or `autoSize`
255  - ✅ Wrap root component: `<McpUseProvider autoSize>`
256- ❌ Inline styles without theme awareness
257  - ✅ Use `useWidgetTheme()` for light/dark mode support
258 
259### Security & Production
260- ❌ Hardcoded API keys or secrets in code
261  - ✅ Use `process.env.API_KEY`, document in `.env.example`
262- ❌ No error handling in tool handlers
263  - ✅ Wrap in try/catch, return `error()` on failure
264- ❌ Expensive operations without caching
265  - ✅ Cache API calls, computations with TTL
266- ❌ Missing CORS configuration
267  - ✅ Configure CORS for production deployments
268 
269---
270 
271## 🔒 Golden Rules
272 
273**Opinionated architectural guidelines:**
274 
275### 1. One Tool = One Capability
276Split broad actions into focused tools:
277- ❌ `manage-users` (too vague)
278- ✅ `create-user`, `delete-user`, `list-users`
279 
280### 2. Return Complete Data Upfront
281Tool calls are expensive. Avoid lazy-loading:
282- ❌ `list-products` + `get-product-details` (2 calls)
283- ✅ `list-products` returns full data including details
284 
285### 3. Widgets Own Their State
286UI state lives in the widget, not in separate tools:
287- ❌ `select-item` tool, `set-filter` tool
288- ✅ Widget manages with `useState` or `setState`
289 
290### 4. `exposeAsTool` Defaults to `false`
291Widgets are registered as resources only by default. Use a custom tool (recommended) or set `exposeAsTool: true` to expose a widget to the model:
292 
293```typescript
294// ✅ ALL 4 STEPS REQUIRED for proper type inference:
295 
296// Step 1: Define schema separately
297const propsSchema = z.object({
298  title: z.string(),
299  items: z.array(z.string())
300});
301 
302// Step 2: Reference schema variable in metadata
303export const widgetMetadata: WidgetMetadata = {
304  description: "...",
305  props: propsSchema,  // ← NOT inline z.object()
306  exposeAsTool: false
307};
308 
309// Step 3: Infer Props type from schema variable
310type Props = z.infer<typeof propsSchema>;
311 
312// Step 4: Use typed Props with useWidget
313export default function MyWidget() {
314  const { props, isPending } = useWidget<Props>();  // ← Add <Props>
315  // ...
316}
317```
318 
319⚠️ **Common mistake:** Only doing steps 1-2 but skipping 3-4 (loses type safety)
320 
321### 5. Validate at Boundaries Only
322- Trust internal code and framework guarantees
323- Validate user input, external API responses
324- Don't add error handling for scenarios that can't happen
325 
326### 6. Prefer Widgets for Browsing/Comparing
327When in doubt, add a widget. Visual UI improves:
328- Browsing multiple items
329- Comparing data side-by-side
330- Interactive selection workflows
331 
332---
333 
334## Quick Reference
335 
336### Minimal Server
337```typescript
338import { MCPServer, text } from "mcp-use/server";
339import { z } from "zod";
340 
341const server = new MCPServer({
342  name: "my-server",
343  title: "My Server",
344  version: "1.0.0"
345});
346 
347server.tool(
348  {
349    name: "greet",
350    description: "Greet a user",
351    schema: z.object({ name: z.string().describe("User's name") })
352  },
353  async ({ name }) => text("Hello " + name + "!"),
354);
355 
356server.listen();
357```
358 
359---
360 
361## Response Helpers
362 
363| Helper | Use When | Example |
364|--------|----------|---------|
365| `text()` | Simple string response | `text("Success!")` |
366| `object()` | Structured data | `object({ status: "ok" })` |
367| `markdown()` | Formatted text | `markdown("# Title\nContent")` |
368| `widget()` | Visual UI | `widget({ props: {...}, output: text(...) })` |
369| `mix()` | Multiple contents | `mix(text("Hi"), image(url))` |
370| `error()` | Error responses | `error("Failed to fetch data")` |
371| `resource()` | Embed resource refs | `resource("docs://guide", "text/markdown")` |
372 
373**Server methods:**
374- `server.tool()` - Define executable tool
375- `server.resource()` - Define static/dynamic resource
376- `server.resourceTemplate()` - Define parameterized resource
377- `server.prompt()` - Define prompt template
378- `server.proxy()` - Compose/Proxy multiple MCP servers
379- `server.uiResource()` - Define widget resource
380- `server.listen()` - Start server
381- `server.use('mcp:tools/call', fn)` - MCP middleware (tools, resources, prompts, list ops)
382- `server.use('mcp:*', fn)` - Catch-all MCP middleware
383- `server.use(fn)` - HTTP middleware (Hono)
384 
385 
386