1# Tools
2 
3Tools are backend actions the AI can call. They take structured input and return output.
4 
5**Use tools for:** Actions, operations, API calls, mutations, data fetching
6 
7---
8 
9## Basic Tool
10 
11```typescript
12import { MCPServer, text } from "mcp-use/server";
13import { z } from "zod";
14 
15const server = new MCPServer({
16  name: "my-server",
17  version: "1.0.0",
18  baseUrl: process.env.MCP_URL || "http://localhost:3000"
19});
20 
21server.tool(
22  {
23    name: "send-email",
24    description: "Send an email to a user",
25    schema: z.object({
26      to: z.string().email().describe("Recipient email address"),
27      subject: z.string().describe("Email subject line"),
28      body: z.string().describe("Email body content"),
29      priority: z.enum(["low", "normal", "high"]).optional().describe("Email priority")
30    })
31  },
32  async ({ to, subject, body, priority = "normal" }) => {
33    // Your logic here
34    await sendEmail(to, subject, body, priority);
35    return text(`Email sent to ${to}`);
36  }
37);
38```
39 
40**Key points:**
41- First argument: tool configuration (name, description, schema)
42- Second argument: async handler function
43- Handler receives validated input matching schema
44- Must return a response helper (`text()`, `object()`, `widget()`, etc.)
45 
46---
47 
48## Tool Definition
49 
50### Name
51- Use kebab-case: `send-email`, `fetch-user`, `create-todo`
52- Be specific: ❌ `manage-users` ✅ `create-user`, `delete-user`, `list-users`
53- One tool = one capability
54 
55### Description
56Clear, actionable description of what the tool does:
57```typescript
58✅ "Send an email to a user with subject and body"
59❌ "Email tool"
60```
61 
62The AI uses this to decide when to call your tool.
63 
64### Schema (Zod)
65 
66**Always use `.describe()` on every field:**
67```typescript
68// ✅ Good
69z.object({
70  city: z.string().describe("City name (e.g., 'New York', 'Tokyo')"),
71  units: z.enum(["celsius", "fahrenheit"]).optional().describe("Temperature units"),
72  limit: z.number().min(1).max(50).optional().describe("Max results to return")
73})
74 
75// ❌ Bad - no descriptions
76z.object({
77  city: z.string(),
78  units: z.string(),
79  limit: z.number()
80})
81```
82 
83**Schema best practices:**
84- Use `.optional()` for non-required fields
85- Add validation: `.min()`, `.max()`, `.email()`, `.url()`
86- Use `z.enum()` for fixed sets of values (not `z.string()`)
87- Use `z.array()` for lists
88- Use `z.record(z.string(), z.string())` for key-value maps (Zod v4 requires both key and value schemas)
89 
90---
91 
92## Tool Annotations
93 
94Declare the nature of your tool so clients can warn users:
95 
96```typescript
97server.tool(
98  {
99    name: "delete-user",
100    description: "Permanently delete a user account",
101    schema: z.object({ userId: z.string().describe("User ID") }),
102    annotations: {
103      destructiveHint: true,    // Deletes or overwrites data
104      readOnlyHint: false,      // Has side effects
105      openWorldHint: false      // Stays within user's account (not external APIs)
106    }
107  },
108  async ({ userId }) => {
109    await deleteUser(userId);
110    return text(`User ${userId} deleted`);
111  }
112);
113```
114 
115**Annotations:**
116- `destructiveHint: true` - Deletes/overwrites data, client may require confirmation
117- `readOnlyHint: true` - No side effects, safe to call repeatedly
118- `openWorldHint: true` - Calls external APIs or services outside user's control
119 
120---
121 
122## Tool Context
123 
124The second parameter to tool handlers provides advanced capabilities:
125 
126```typescript
127server.tool(
128  {
129    name: "process-large-file",
130    schema: z.object({ fileUrl: z.string().describe("URL to file") })
131  },
132  async ({ fileUrl }, ctx) => {
133    // Progress reporting
134    await ctx.reportProgress?.(0, 100, "Starting download...");
135    const file = await downloadFile(fileUrl);
136 
137    await ctx.reportProgress?.(50, 100, "Processing...");
138    const result = await processFile(file);
139 
140    // Structured logging
141    await ctx.log("info", `Processed ${file.size} bytes`);
142 
143    // Structured logging with additional context (optional third parameter)
144    await ctx.log("info", "Processing complete", `fileSize: ${file.size} bytes, duration: 2.5s`);
145 
146    // Check client capabilities
147    if (ctx.client.can("sampling")) {
148      // Ask the LLM to help analyze results
149      const summary = await ctx.sample(`Summarize this data: ${result}`);
150      return text(summary);
151    }
152 
153    await ctx.reportProgress?.(100, 100, "Complete");
154    return object(result);
155  }
156);
157```
158 
159**Context methods:**
160- `ctx.reportProgress(current: number, total: number, message: string)` - Show progress to user
161- `ctx.log(level: "debug" | "info" | "warn" | "error", message: string, data?: string)` - Structured logging with optional additional context as a string
162- `ctx.sample(prompt: string)` - Ask the LLM for help (requires client support)
163- `ctx.client.can(capability: string)` - Check if client supports a feature
164 
165### Client Identity & Caller Context
166 
167`ctx.client` also exposes per-invocation caller context from `params._meta`:
168 
169```typescript
170server.tool({ name: "personalise", schema: z.object({}) }, async (_p, ctx) => {
171  // Session-level (stable for the connection lifetime)
172  const { name, version } = ctx.client.info();   // "openai-mcp", "1.0.0"
173  const isAppsClient = ctx.client.supportsApps(); // true for ChatGPT
174 
175  // Per-invocation — may differ on every tool call
176  const caller = ctx.client.user();
177  if (caller) {
178    const city = caller.location?.city ?? "there";
179    const greeting = caller.locale?.startsWith("it") ? "Ciao" : "Hello";
180    return text(`${greeting} from ${city}! (via ${name})`);
181  }
182  return text(`Hello! (via ${name})`);
183});
184```
185 
186**`ctx.client.user()` fields:**
187- `subject` — stable opaque user ID (same across conversations, e.g. `openai/subject`)
188- `conversationId` — current chat thread ID (changes per chat, e.g. `openai/session`)
189- `locale` — BCP-47 locale, e.g. `"it-IT"` (server-side; inside widgets prefer `useWidget().locale` which is client-side and fresher)
190- `location` — `{ city, region, country, timezone, latitude, longitude }`
191- `userAgent` — browser/host user-agent string
192- `timezoneOffsetMinutes` — UTC offset in minutes
193 
194**Key rules:**
195- Returns `undefined` on clients that don't send this metadata (Inspector, CLI, non-ChatGPT clients)
196- **Unverified / advisory** — self-reported by the client, not suitable for access control
197- For verified identity, use `ctx.auth` (requires OAuth)
198 
199**ChatGPT multi-tenant model:**
200ChatGPT uses a single MCP session for ALL users of a deployed app. Use `ctx.client.user()` to distinguish callers:
201 
202```
2031 MCP session  ctx.session.sessionId              — shared across ALL users
204  N subjects   ctx.client.user()?.subject         — one per ChatGPT user account
205    M threads  ctx.client.user()?.conversationId  — one per chat conversation
206```
207 
208```typescript
209// Identify who is calling this specific invocation
210const caller = ctx.client.user();
211return object({
212  mcpSession: ctx.session.sessionId,           // shared transport session
213  user: caller?.subject ?? null,                // ChatGPT user ID
214  conversation: caller?.conversationId ?? null, // this chat thread
215});
216```
217 
218---
219 
220## Error Handling
221 
222**Always use `error()` helper, don't throw:**
223 
224```typescript
225import { text, error } from "mcp-use/server";
226 
227server.tool(
228  { name: "fetch-user", schema: z.object({ id: z.string() }) },
229  async ({ id }) => {
230    try {
231      const user = await fetchUser(id);
232 
233      if (!user) {
234        return error(`User not found: ${id}`);
235      }
236 
237      return object(user);
238    } catch (err) {
239      // Log for debugging
240      console.error("Failed to fetch user:", err);
241 
242      // Return error to client
243      return error(
244        `Failed to fetch user: ${err instanceof Error ? err.message : "Unknown error"}`
245      );
246    }
247  }
248);
249```
250 
251**Error handling rules:**
252- ✅ Return `error()` for graceful failure
253- ❌ Don't throw exceptions (client sees raw error)
254- ✅ Include helpful context in error messages
255- ✅ Log errors server-side for debugging
256 
257---
258 
259## Tool with Widget
260 
261When your tool returns visual UI:
262 
263```typescript
264import { widget, text } from "mcp-use/server";
265 
266server.tool(
267  {
268    name: "search-products",
269    description: "Search products by keyword",
270    schema: z.object({
271      query: z.string().describe("Search query")
272    }),
273    widget: {
274      name: "product-list",           // Must match resources/product-list.tsx
275      invoking: "Searching products...",
276      invoked: "Products loaded"
277    }
278  },
279  async ({ query }) => {
280    const products = await searchProducts(query);
281 
282    return widget({
283      props: {
284        products,
285        query,
286        totalCount: products.length
287      },
288      output: text(`Found ${products.length} products matching "${query}"`)
289    });
290  }
291);
292```
293 
294**Widget tool requirements:**
295- Add `widget: { name }` to tool config
296- Return `widget({ props, output })` from handler
297- Create matching widget file: `resources/{name}.tsx`
298- `exposeAsTool` defaults to `false` — omitting it is correct for this pattern
299 
300See [../widgets/basics.md](../widgets/basics.md) for widget implementation.
301 
302---
303 
304## Structured Output Schema
305 
306Validate tool output at runtime:
307 
308```typescript
309server.tool(
310  {
311    name: "calculate-stats",
312    schema: z.object({
313      data: z.array(z.number()).describe("Array of numbers")
314    }),
315    outputSchema: z.object({
316      mean: z.number(),
317      median: z.number(),
318      stdDev: z.number(),
319      count: z.number()
320    })
321  },
322  async ({ data }) => {
323    const stats = calculateStats(data);
324 
325    // Output is validated against outputSchema
326    return object({
327      mean: stats.mean,
328      median: stats.median,
329      stdDev: stats.stdDev,
330      count: data.length
331    });
332  }
333);
334```
335 
336**When to use `outputSchema`:**
337- You want runtime validation of tool output
338- Multiple code paths return different shapes
339- Debugging output consistency issues
340 
341---
342 
343## Environment Variables
344 
345Securely handle API keys and configuration:
346 
347```typescript
348// index.ts
349const WEATHER_API_KEY = process.env.WEATHER_API_KEY;
350 
351server.tool(
352  {
353    name: "get-weather",
354    schema: z.object({ city: z.string() })
355  },
356  async ({ city }) => {
357    if (!WEATHER_API_KEY) {
358      return error(
359        "WEATHER_API_KEY not configured. Please set it in environment variables."
360      );
361    }
362 
363    const data = await fetch(
364      `https://api.weather.com/v1?key=${WEATHER_API_KEY}&city=${city}`
365    );
366 
367    // ... rest of logic
368  }
369);
370```
371 
372**Best practices:**
373- ❌ Never hardcode secrets in code
374- ✅ Use `process.env.VAR_NAME`
375- ✅ Check if required vars are set
376- ✅ Document required vars in `.env.example`
377 
378**Example `.env.example`:**
379```bash
380# Weather API key (get from weatherapi.com)
381WEATHER_API_KEY=
382 
383# Database connection string
384DATABASE_URL=
385```
386 
387---
388 
389## Performance Patterns
390 
391### Caching
392 
393Cache expensive operations:
394 
395```typescript
396const cache = new Map<string, { data: any; expires: number }>();
397 
398server.tool(
399  { name: "fetch-weather", schema: z.object({ city: z.string() }) },
400  async ({ city }) => {
401    const cacheKey = `weather:${city}`;
402    const cached = cache.get(cacheKey);
403 
404    // Return cached data if not expired
405    if (cached && cached.expires > Date.now()) {
406      return object(cached.data);
407    }
408 
409    // Fetch fresh data
410    const data = await fetchWeather(city);
411 
412    // Cache for 5 minutes
413    cache.set(cacheKey, {
414      data,
415      expires: Date.now() + 5 * 60 * 1000
416    });
417 
418    return object(data);
419  }
420);
421```
422 
423### Rate Limiting
424 
425Prevent abuse using `hono-rate-limiter`:
426 
427```typescript
428import { rateLimiter } from "hono-rate-limiter";
429 
430server.use(rateLimiter({
431  windowMs: 15 * 60 * 1000, // 15 minutes
432  limit: 100, // 100 requests per window per key
433  keyGenerator: (c) =>
434    c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
435    c.req.header("cf-connecting-ip") ??
436    c.req.header("x-real-ip") ??
437    "unknown",
438}));
439```
440 
441> Adjust the key generator depending on your hosting environment.
442 
443**Note:** mcp-use is built on Hono and supports both Hono-compatible middleware and Express middleware. Express middleware (e.g., `express-rate-limit`, `morgan`) is automatically detected and adapted. For custom middleware or advanced routing, see [../foundations/architecture.md](../foundations/architecture.md).
444 
445---
446 
447## Security Checklist
448 
449Before deploying tools:
450 
451- [ ] All schema fields have `.describe()`
452- [ ] Input validation with Zod
453- [ ] User input sanitized (no SQL injection, XSS)
454- [ ] API keys in environment variables
455- [ ] Errors return `error()` helper (not thrown)
456- [ ] Try/catch around async operations
457- [ ] Rate limiting on expensive operations
458- [ ] Destructive operations have `destructiveHint: true`
459 
460---
461 
462## Next Steps
463 
464- **Format responses** → [response-helpers.md](response-helpers.md)
465- **Add visual UI** → [../widgets/basics.md](../widgets/basics.md)
466- **See examples** → [../patterns/common-patterns.md](../patterns/common-patterns.md)
467