1# Resources
2 
3Resources expose read-only data that clients can fetch. They don't take input parameters (use resource templates for that).
4 
5**Use resources for:** Configuration, static data, documentation, listings, app state
6 
7---
8 
9## Basic Resource
10 
11```typescript
12import { MCPServer, object, text, markdown } from "mcp-use/server";
13 
14const server = new MCPServer({
15  name: "my-server",
16  version: "1.0.0"
17});
18 
19server.resource(
20  {
21    name: "app_settings",
22    uri: "config://settings",
23    title: "Application Settings",
24    description: "Current server configuration"
25  },
26  async () => object({
27    theme: "dark",
28    version: "1.0.0",
29    language: "en",
30    features: {
31      notifications: true,
32      analytics: false
33    }
34  })
35);
36```
37 
38**Key points:**
39- First argument: resource configuration (uri, name, description, mimeType)
40- Second argument: async handler function (no input parameters)
41- Handler returns response helper (`object()`, `text()`, `markdown()`, etc.)
42- URI scheme is arbitrary (use meaningful prefixes: `config://`, `docs://`, `data://`)
43 
44---
45 
46## Resource Definition
47 
48### URI
49Use a scheme-based format for organization:
50 
51```typescript
52✅ "config://settings"          // Configuration data
53✅ "docs://user-guide"          // Documentation
54✅ "data://available-cities"    // Static data
55✅ "state://current-user"       // Current state
56 
57❌ "settings"                   // Missing scheme
58❌ "http://example.com/data"    // Don't use http:// (reserved)
59```
60 
61### Name
62Machine-readable identifier (kebab-case):
63```typescript
64✅ "app_settings"
65✅ "user_guide"
66✅ "available_cities"
67```
68 
69### Title
70Human-readable name shown to users:
71```typescript
72✅ "Application Settings"
73✅ "User Guide"
74✅ "Available Cities"
75```
76 
77### Description
78Optional but recommended. Explains what the resource contains:
79```typescript
80description: "Current server configuration including theme, language, and feature flags"
81```
82 
83### MIME Type
84Indicates content format:
85 
86| Content Type | MIME Type |
87|--------------|-----------|
88| JSON object | `application/json` |
89| Plain text | `text/plain` |
90| Markdown | `text/markdown` |
91| HTML | `text/html` |
92| Image | `image/png`, `image/jpeg` |
93| Binary | `application/octet-stream` |
94 
95---
96 
97## Static Resources
98 
99Resources that return fixed data:
100 
101```typescript
102server.resource(
103  {
104    name: "supported_languages",
105    uri: "data://supported-languages",
106    title: "Supported Languages",
107    description: "List of supported language codes"
108  },
109  async () => object({
110    languages: ["en", "es", "fr", "de", "ja"],
111    default: "en"
112  })
113);
114 
115server.resource(
116  {
117    name: "api_guide",
118    uri: "docs://api-guide",
119    title: "API Documentation",
120    description: "Complete API reference and examples"
121  },
122  async () => markdown(`
123# API Guide
124 
125## Authentication
126Use Bearer token in Authorization header...
127 
128## Endpoints
129- POST /api/users - Create user
130- GET /api/users/:id - Get user
131  `)
132);
133```
134 
135---
136 
137## Dynamic Resources
138 
139Resources that fetch or compute data at request time:
140 
141```typescript
142server.resource(
143  {
144    name: "current_stats",
145    uri: "stats://current",
146    title: "Current Statistics",
147    description: "Real-time server statistics"
148  },
149  async () => {
150    const stats = await calculateStats();
151 
152    return object({
153      users: stats.totalUsers,
154      requests: stats.requestCount,
155      uptime: process.uptime(),
156      timestamp: new Date().toISOString()
157    });
158  }
159);
160 
161server.resource(
162  {
163    name: "active_sessions",
164    uri: "state://active-sessions",
165    title: "Active Sessions",
166    description: "Currently active user sessions"
167  },
168  async () => {
169    const sessions = await getActiveSessions();
170 
171    return object({
172      count: sessions.length,
173      sessions: sessions.map(s => ({
174        id: s.id,
175        user: s.userId,
176        started: s.startTime
177      }))
178    });
179  }
180);
181```
182 
183**When to use dynamic resources:**
184- Data changes over time
185- Data is expensive to compute (compute on demand)
186- Data reflects current server state
187 
188---
189 
190## Resource Templates
191 
192When you need parameters, use resource templates with URI placeholders:
193 
194```typescript
195server.resourceTemplate(
196  {
197    name: "user_profile",
198    uriTemplate: "user://{userId}/profile",
199    title: "User Profile",
200    description: "Get user profile by ID"
201  },
202  async (uri: URL, params: Record<string, string>) => {
203    // Extract parameters from params object
204    const { userId } = params;
205 
206    const user = await fetchUser(userId);
207 
208    if (!user) {
209      return error(`User not found: ${userId}`);
210    }
211 
212    return object({
213      id: user.id,
214      name: user.name,
215      email: user.email,
216      createdAt: user.createdAt
217    });
218  }
219);
220```
221 
222**URI template syntax:**
223- `{param}` - Single path segment
224- `{param*}` - Multiple path segments (greedy)
225 
226**Examples:**
227```typescript
228// Single parameter
229"user://{userId}/profile"        // Matches: user://123/profile
230"docs://{section}"               // Matches: docs://getting-started
231 
232// Multiple parameters
233"files://{folder}/{filename}"    // Matches: files://documents/report.pdf
234"api://{version}/users/{id}"     // Matches: api://v1/users/42
235 
236// Greedy parameter (matches multiple segments)
237"docs://{path*}"                 // Matches: docs://guides/api/authentication
238```
239 
240**Handler signature:**
241```typescript
242async (uri: URL, params: Record<string, string>) => {
243  // uri: URL object of the matched URI
244  // params: Record<string, string> with extracted template parameters
245 
246  // Extract the parameters you need
247  const { userId } = params;
248}
249```
250 
251**⚠️ TypeScript Best Practice:**
252- **Recommended:** Use explicit types and extract params inside the function body (as shown above)
253- **Not recommended:** Parameter destructuring like `async (uri, { userId }) => {}` works at runtime but TypeScript has trouble matching it against the `Record<string, string>` type, potentially causing compilation errors
254 
255---
256 
257## Completion (Autocomplete) for Templates
258 
259Add autocomplete suggestions for resource template variables using the `callbacks.complete` option:
260 
261```typescript
262// Static list of suggestions per variable
263server.resourceTemplate(
264  {
265    uriTemplate: "docs://{docId}",
266    name: "Documentation",
267    description: "Get documentation by ID",
268    callbacks: {
269      complete: {
270        docId: ["getting-started", "api-reference", "faq", "changelog"]
271      }
272    }
273  },
274  async (uri: URL, params: Record<string, string>) => {
275    const { docId } = params;
276    return markdown(await fetchDoc(docId));
277  }
278);
279 
280// Dynamic suggestions via callback
281server.resourceTemplate(
282  {
283    uriTemplate: "user://{userId}/profile",
284    name: "User Profile",
285    callbacks: {
286      complete: {
287        userId: async (value: string) => {
288          const users = await searchUsers(value);
289          return users.map(u => u.id);
290        }
291      }
292    }
293  },
294  async (uri: URL, params: Record<string, string>) => {
295    const { userId } = params;
296    return object(await fetchUser(userId));
297  }
298);
299```
300 
301**Key points:**
302- `complete` maps each template variable to either a `string[]` (prefix-matched automatically) or a callback `(value: string) => Promise<string[]>`
303- Clients request suggestions via MCP `completion/complete`
304 
305---
306 
307## Error Handling
308 
309Resources can fail - handle errors gracefully with `error()` helper:
310 
311```typescript
312server.resource({ uri: "data://external-api", ... }, async () => {
313  try {
314    const data = await fetch("https://api.example.com/data");
315    if (!data.ok) return error(`API returned status ${data.status}`);
316    return object(await data.json());
317  } catch (err) {
318    return error(`Failed to fetch: ${err.message}`);
319  }
320});
321```
322 
323See [tools.md](tools.md#error-handling) for comprehensive error handling patterns.
324 
325---
326 
327## Listing Resources
328 
329Clients can list all available resources. Organize resources by URI scheme for discoverability:
330 
331```typescript
332// Good organization
333server.resource({ uri: "config://settings", ... });
334server.resource({ uri: "config://features", ... });
335server.resource({ uri: "config://limits", ... });
336 
337server.resource({ uri: "docs://guide", ... });
338server.resource({ uri: "docs://api", ... });
339server.resource({ uri: "docs://faq", ... });
340 
341server.resource({ uri: "data://cities", ... });
342server.resource({ uri: "data://countries", ... });
343```
344 
345When a client lists resources, they see:
346```json
347{
348  "resources": [
349    { "uri": "config://settings", "name": "Application Settings", ... },
350    { "uri": "config://features", "name": "Feature Flags", ... },
351    { "uri": "docs://guide", "name": "User Guide", ... },
352    ...
353  ]
354}
355```
356 
357---
358 
359## Resource vs Tool
360 
361**Use a resource when:**
362- ✅ Read-only data
363- ✅ No input parameters (or use resource templates)
364- ✅ Data that clients might browse or list
365- ✅ Configuration, docs, static data
366 
367**Use a tool when:**
368- ✅ Action with side effects
369- ✅ Complex input validation needed
370- ✅ Needs Zod schema for structured input
371- ✅ May return visual UI (widgets)
372 
373**Example:**
374```typescript
375// ❌ Bad - Use resource instead
376server.tool(
377  { name: "get-settings", schema: z.object({}) },
378  async () => object({ theme: "dark" })
379);
380 
381// ✅ Good
382server.resource(
383  { uri: "config://settings", ... },
384  async () => object({ theme: "dark" })
385);
386 
387// ✅ Good - Tool appropriate here (has input)
388server.tool(
389  { name: "update-settings", schema: z.object({ theme: z.string() }) },
390  async ({ theme }) => {
391    await saveSettings({ theme });
392    return text("Settings updated");
393  }
394);
395```
396 
397---
398 
399## Caching Resources
400 
401Since resources are read-only, caching is often beneficial:
402 
403```typescript
404const cache = new Map<string, { data: any; expires: number }>();
405 
406server.resource(
407  {
408    uri: "data://expensive-computation",
409    name: "Expensive Data",
410    mimeType: "application/json"
411  },
412  async () => {
413    const cacheKey = "expensive-computation";
414    const cached = cache.get(cacheKey);
415 
416    // Return cached data if not expired
417    if (cached && cached.expires > Date.now()) {
418      return object(cached.data);
419    }
420 
421    // Compute fresh data
422    const data = await expensiveComputation();
423 
424    // Cache for 10 minutes
425    cache.set(cacheKey, {
426      data,
427      expires: Date.now() + 10 * 60 * 1000
428    });
429 
430    return object(data);
431  }
432);
433```
434 
435---
436 
437## Complete Example
438 
439```typescript
440import { MCPServer, object, markdown, error } from "mcp-use/server";
441 
442const server = new MCPServer({
443  name: "docs-server",
444  version: "1.0.0"
445});
446 
447// Static configuration
448server.resource(
449  {
450    uri: "config://settings",
451    name: "Server Settings",
452    mimeType: "application/json"
453  },
454  async () => object({
455    version: "1.0.0",
456    environment: process.env.NODE_ENV || "development"
457  })
458);
459 
460// Dynamic list
461server.resource(
462  {
463    uri: "data://available-docs",
464    name: "Available Documentation",
465    mimeType: "application/json"
466  },
467  async () => {
468    const docs = await listDocuments();
469    return object({ docs });
470  }
471);
472 
473// Parameterized access
474server.resourceTemplate(
475  {
476    uriTemplate: "docs://{docId}",
477    name: "Documentation",
478    description: "Get documentation by ID",
479    mimeType: "text/markdown"
480  },
481  async (uri: URL, params: Record<string, string>) => {
482    const { docId } = params;
483    const doc = await fetchDocument(docId);
484 
485    if (!doc) {
486      return error(`Document not found: ${docId}`);
487    }
488 
489    return markdown(doc.content);
490  }
491);
492 
493server.listen();
494```
495 
496---
497 
498## Next Steps
499 
500- **Format responses** → [response-helpers.md](response-helpers.md)
501- **Create tools** → [tools.md](tools.md)
502- **See examples** → [../patterns/common-patterns.md](../patterns/common-patterns.md)
503