1# Quick Start
2 
3Build your first MCP server tool in 5 minutes.
4 
5## Setup
6 
7### Scaffolding a New Project
8 
9```bash
10npx create-mcp-use-app my-server
11cd my-server
12npm run dev
13```
14 
15This installs dependencies, starts the server on port 3000, and opens the inspector at `http://localhost:3000/inspector`.
16 
17### Choosing a Template
18 
19Pick the template that matches what the user is building:
20 
21| Template | Command | Use When |
22|----------|---------|----------|
23| **starter** (default) | `npx create-mcp-use-app my-server` | Full-featured server with tools, resources, prompts, and widget examples |
24| **mcp-apps** | `npx create-mcp-use-app my-server --template mcp-apps` | Widget-focused for ChatGPT, Claude, and other MCP Apps-compatible clients |
25| **blank** | `npx create-mcp-use-app my-server --template blank` | Clean slate — bare server with commented-out examples |
26| **GitHub repo** | `npx create-mcp-use-app my-server --template owner/repo` | Custom or community templates from any GitHub repository |
27 
28**When unsure, use `mcp-apps`.** It's the recommended default with widget support for ChatGPT, Claude, and other MCP Apps-compatible clients.
29 
30### Common Flags
31 
32```bash
33# Choose package manager
34npx create-mcp-use-app my-server --npm
35npx create-mcp-use-app my-server --pnpm
36 
37# Skip interactive prompts
38npx create-mcp-use-app my-server --install --skills
39 
40# List all available templates
41npx create-mcp-use-app --list-templates
42```
43 
44### What Each Template Produces
45 
46**starter:**
47```
48my-server/
49├── index.ts              # Server with example tool, resource, and prompt
50├── resources/            # Widget directory (display-weather.tsx example)
51├── public/               # Static assets (favicon, icon)
52├── package.json          # Pre-configured scripts: dev, build, start, deploy
53└── tsconfig.json
54```
55 
56**mcp-apps:**
57```
58my-server/
59├── index.ts              # Server with widget-returning tools
60├── resources/            # Widget directory (product-search-result/ example)
61│   └── product-search-result/
62│       ├── widget.tsx    # React widget with carousel UI
63│       └── components/   # Reusable widget components
64├── public/
65├── package.json
66└── tsconfig.json
67```
68 
69**blank:**
70```
71my-server/
72├── index.ts              # Bare MCPServer with commented-out examples
73├── public/
74├── package.json
75└── tsconfig.json
76```
77 
78### Development Workflow
79 
80After scaffolding:
81 
821. `npm run dev` — starts server with hot reload + inspector
832. Edit `index.ts` to add tools, resources, prompts
843. Add widgets as `.tsx` files in `resources/`
854. Test everything at `http://localhost:3000/inspector`
865. `npm run build` — production build
876. `npm run deploy` — deploy to production
88 
89---
90 
91## Your First Tool
92 
93Open `index.ts` and you'll see a basic server. Let's add a simple tool:
94 
95```typescript
96import { MCPServer, text } from "mcp-use/server";
97import { z } from "zod";
98 
99const server = new MCPServer({
100  name: "my-server",
101  title: "My Server",
102  version: "1.0.0",
103  baseUrl: process.env.MCP_URL || "http://localhost:3000"
104});
105 
106// Add this tool
107server.tool(
108  {
109    name: "greet",
110    description: "Greet a user by name",
111    schema: z.object({
112      name: z.string().describe("User's name")
113    })
114  },
115  async ({ name }) => {
116    return text(`Hello, ${name}! Welcome to MCP.`);
117  }
118);
119 
120server.listen();
121```
122 
123**Save the file** - the server auto-reloads!
124 
125**Test it:**
1261. Open inspector (`http://localhost:3000/inspector`)
1272. Click "List Tools"
1283. Find "greet" tool
1294. Click "Call Tool"
1305. Enter `{"name": "Alice"}`
1316. See response: "Hello, Alice! Welcome to MCP."
132 
133---
134 
135## Add Mock Data
136 
137Let's build a weather tool with mock data:
138 
139```typescript
140// Mock weather data
141const mockWeather: Record<string, { temp: number; conditions: string }> = {
142  "New York": { temp: 22, conditions: "Partly Cloudy" },
143  "London": { temp: 15, conditions: "Rainy" },
144  "Tokyo": { temp: 28, conditions: "Sunny" },
145  "Paris": { temp: 18, conditions: "Overcast" }
146};
147 
148server.tool(
149  {
150    name: "get-weather",
151    description: "Get current weather for a city",
152    schema: z.object({
153      city: z.string().describe("City name")
154    })
155  },
156  async ({ city }) => {
157    const weather = mockWeather[city];
158 
159    if (!weather) {
160      return text(`No weather data for ${city}`);
161    }
162 
163    return text(
164      `Weather in ${city}: ${weather.temp}°C, ${weather.conditions}`
165    );
166  }
167);
168```
169 
170**Test it:**
171- Call tool with `{"city": "Tokyo"}`
172- Response: "Weather in Tokyo: 28°C, Sunny"
173 
174---
175 
176## Add Structure
177 
178Return structured data with `object()`:
179 
180```typescript
181import { MCPServer, text, object } from "mcp-use/server";
182 
183server.tool(
184  {
185    name: "get-weather-detailed",
186    description: "Get detailed weather information",
187    schema: z.object({
188      city: z.string().describe("City name")
189    })
190  },
191  async ({ city }) => {
192    const weather = mockWeather[city];
193 
194    if (!weather) {
195      return object({ error: `No data for ${city}` });
196    }
197 
198    return object({
199      city,
200      temperature: weather.temp,
201      conditions: weather.conditions,
202      unit: "celsius",
203      timestamp: new Date().toISOString()
204    });
205  }
206);
207```
208 
209---
210 
211## Add a Resource
212 
213Resources provide read-only data:
214 
215```typescript
216server.resource(
217  {
218    name: "available_cities",
219    uri: "weather://available-cities",
220    title: "Available Cities",
221    description: "List of cities with weather data"
222  },
223  async () => object({
224    cities: Object.keys(mockWeather)
225  })
226);
227```
228 
229**Test it:**
2301. Inspector → "List Resources"
2312. Find "Available Cities"
2323. Click "Read Resource"
2334. See: `{"cities": ["New York", "London", "Tokyo", "Paris"]}`
234 
235---
236 
237## Next Steps
238 
239**Now that you have the basics:**
240 
2411. **Learn response helpers** → [../server/response-helpers.md](../server/response-helpers.md)
2422. **Build your first widget** → [../widgets/basics.md](../widgets/basics.md)
2433. **See complete examples** → [../patterns/common-patterns.md](../patterns/common-patterns.md)
244 
245**Want to add visual UI?** Continue to widgets:
246- [Widget Basics](../widgets/basics.md) - Create your first interactive widget
247