1---
2name: mcp-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### 🔁 Testing from the Terminal (Agent Feedback Loops)
193**When:** You want to verify a tool or widget *without* the inspector UI — the canonical flow for AI agents iterating on MCP servers.
194 
195- **`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.
196 
197  ```bash
198  npx mcp-use client connect dev http://localhost:3000/mcp
199  npx mcp-use client dev tools list
200  npx mcp-use client dev tools call get-weather city=Tokyo --screenshot
201  ```
202 
203  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>`).
204 
205- **`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:
206 
207  ```bash
208  # Saved-server form — reuses the auth from `mcp-use client connect`
209  npx mcp-use client dev screenshot --tool get-weather city=Tokyo \
210    --width 800 --height 600 --theme light \
211    --output ./weather.png
212 
213  # Ad-hoc form — connect inline (use -H for headers on authenticated servers)
214  npx mcp-use client screenshot --mcp http://localhost:3000/mcp \
215    --tool get-weather city=Tokyo
216  ```
217 
218  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.
219 
220Both commands are documented in full at [docs/typescript/client/cli](https://docs.mcp-use.com/typescript/client/cli).
221 
222---
223 
224## Decision Tree
225 
226```
227What do you need?
228 
229├─ New project from scratch
230│  └─> quickstart.md (scaffolding + setup)
231│
232├─ OAuth / user authentication
233│  └─> authentication/overview.md → provider-specific guide
234│
235├─ Simple backend action (no UI)
236│  └─> Use Tool: server/tools.md
237│
238├─ Read-only data for clients
239│  └─> Use Resource: server/resources.md
240│
241├─ Reusable prompt template
242│  └─> Use Prompt: server/prompts.md
243│
244├─ Cross-cutting logic (logging, auth checks, rate limiting, tool filtering)
245│  └─> Use Middleware: architecture.md#mcp-middleware
246│
247├─ Visual/interactive UI
248│  └─> Use Widget: widgets/basics.md
249│
250├─ Keep model aware of what user is seeing in widget
251│  └─> widgets/model-context.md
252├─ Upload/download files in a widget
253│  └─> widgets/files.md (ChatGPT Apps SDK only)
254│
255├─ Verify a tool or widget from the terminal (agent feedback loop)
256│  └─> See "Testing from the Terminal" above — `mcp-use client` for tool runs,
257│      `mcp-use client <server> screenshot --tool <tool>` for headless widget PNGs
258│
259└─ Deploy to production
260   └─> deployment.md (cloud deploy, self-hosting, Docker)
261```
262 
263---
264 
265## Core Principles
266 
2671. **Tools for actions** - Backend operations with input/output
2682. **Resources for data** - Read-only data clients can fetch
2693. **Prompts for templates** - Reusable message templates
2704. **Widgets for UI** - Visual interfaces when helpful
2715. **Mock data first** - Prototype quickly, connect APIs later
272 
273---
274 
275## ❌ Common Mistakes
276 
277Avoid these anti-patterns found in production MCP servers:
278 
279### Tool Definition
280- ❌ Returning raw objects instead of using response helpers
281  - ✅ Use `text()`, `object()`, `widget()`, `error()` helpers
282- ❌ Skipping Zod schema `.describe()` on every field
283  - ✅ Add descriptions to all schema fields for better AI understanding
284- ❌ No input validation or sanitization
285  - ✅ Validate inputs with Zod, sanitize user-provided data
286- ❌ Throwing errors instead of returning `error()` helper
287  - ✅ Use `error("message")` for graceful error responses
288 
289### Widget Development
290- ❌ Accessing `props` without checking `isPending`
291  - ✅ Always check `if (isPending) return <Loading/>`
292- ❌ Widget handles server state (filters, selections)
293  - ✅ Widgets manage their own UI state with `useState`
294- ❌ Missing `McpUseProvider` wrapper or `autoSize`
295  - ✅ Wrap root component: `<McpUseProvider autoSize>`
296- ❌ Inline styles without theme awareness
297  - ✅ Use `useWidgetTheme()` for light/dark mode support
298 
299### Security & Production
300- ❌ Hardcoded API keys or secrets in code
301  - ✅ Use `process.env.API_KEY`, document in `.env.example`
302- ❌ No error handling in tool handlers
303  - ✅ Wrap in try/catch, return `error()` on failure
304- ❌ Expensive operations without caching
305  - ✅ Cache API calls, computations with TTL
306- ❌ Missing CORS configuration
307  - ✅ Configure CORS for production deployments
308 
309---
310 
311## 🔒 Golden Rules
312 
313**Opinionated architectural guidelines:**
314 
315### 1. One Tool = One Capability
316Split broad actions into focused tools:
317- ❌ `manage-users` (too vague)
318- ✅ `create-user`, `delete-user`, `list-users`
319 
320### 2. Return Complete Data Upfront
321Tool calls are expensive. Avoid lazy-loading:
322- ❌ `list-products` + `get-product-details` (2 calls)
323- ✅ `list-products` returns full data including details
324 
325### 3. Widgets Own Their State
326UI state lives in the widget, not in separate tools:
327- ❌ `select-item` tool, `set-filter` tool
328- ✅ Widget manages with `useState` or `setState`
329 
330### 4. `exposeAsTool` Defaults to `false`
331Widgets are registered as resources only by default. Use a custom tool (recommended) or set `exposeAsTool: true` to expose a widget to the model:
332 
333```typescript
334// ✅ ALL 4 STEPS REQUIRED for proper type inference:
335 
336// Step 1: Define schema separately
337const propsSchema = z.object({
338  title: z.string(),
339  items: z.array(z.string())
340});
341 
342// Step 2: Reference schema variable in metadata
343export const widgetMetadata: WidgetMetadata = {
344  description: "...",
345  props: propsSchema,  // ← NOT inline z.object()
346  exposeAsTool: false
347};
348 
349// Step 3: Infer Props type from schema variable
350type Props = z.infer<typeof propsSchema>;
351 
352// Step 4: Use typed Props with useWidget
353export default function MyWidget() {
354  const { props, isPending } = useWidget<Props>();  // ← Add <Props>
355  // ...
356}
357```
358 
359⚠️ **Common mistake:** Only doing steps 1-2 but skipping 3-4 (loses type safety)
360 
361### 5. Validate at Boundaries Only
362- Trust internal code and framework guarantees
363- Validate user input, external API responses
364- Don't add error handling for scenarios that can't happen
365 
366### 6. Prefer Widgets for Browsing/Comparing
367When in doubt, add a widget. Visual UI improves:
368- Browsing multiple items
369- Comparing data side-by-side
370- Interactive selection workflows
371 
372---
373 
374## Quick Reference
375 
376### Minimal Server
377```typescript
378import { MCPServer, text } from "mcp-use/server";
379import { z } from "zod";
380 
381const server = new MCPServer({
382  name: "my-server",
383  title: "My Server",
384  version: "1.0.0"
385});
386 
387server.tool(
388  {
389    name: "greet",
390    description: "Greet a user",
391    schema: z.object({ name: z.string().describe("User's name") })
392  },
393  async ({ name }) => text("Hello " + name + "!"),
394);
395 
396server.listen();
397```
398 
399---
400 
401## Response Helpers
402 
403| Helper | Use When | Example |
404|--------|----------|---------|
405| `text()` | Simple string response | `text("Success!")` |
406| `object()` | Structured data | `object({ status: "ok" })` |
407| `markdown()` | Formatted text | `markdown("# Title\nContent")` |
408| `widget()` | Visual UI | `widget({ props: {...}, output: text(...) })` |
409| `mix()` | Multiple contents | `mix(text("Hi"), image(url))` |
410| `error()` | Error responses | `error("Failed to fetch data")` |
411| `resource()` | Embed resource refs | `resource("docs://guide", "text/markdown")` |
412 
413**Server methods:**
414- `server.tool()` - Define executable tool
415- `server.resource()` - Define static/dynamic resource
416- `server.resourceTemplate()` - Define parameterized resource
417- `server.prompt()` - Define prompt template
418- `server.proxy()` - Compose/Proxy multiple MCP servers
419- `server.uiResource()` - Define widget resource
420- `server.listen()` - Start server
421- `server.use('mcp:tools/call', fn)` - MCP middleware (tools, resources, prompts, list ops)
422- `server.use('mcp:*', fn)` - Catch-all MCP middleware
423- `server.use(fn)` - HTTP middleware (Hono)
424 
425 
426