1# MCP Concepts
2 
3Core primitives you'll use to build MCP servers with mcp-use.
4 
5## The Four Primitives
6 
7### 1. Tool
8A **backend action** the AI can call. Takes input, returns output.
9 
10**Use for:** Actions, operations, mutations, API calls
11 
12```typescript
13server.tool({ name, description, schema }, async (input) => {
14  // Your logic here
15  return text("result");
16});
17```
18 
19→ **Detailed guide:** [../server/tools.md](../server/tools.md)
20 
21### 2. Resource
22**Read-only data** that clients can fetch. No input parameters (use resource templates for that).
23 
24**Use for:** Configuration, static data, listings
25 
26```typescript
27server.resource({ uri, name, mimeType }, async () => {
28  return object({ data });
29});
30```
31 
32→ **Detailed guide:** [../server/resources.md](../server/resources.md)
33 
34### 3. Prompt
35A **reusable message template** with parameters.
36 
37**Use for:** Common prompts, instruction templates
38 
39```typescript
40server.prompt({ name, description, schema }, async (input) => {
41  return text(`Your prompt template with ${input.param}`);
42});
43```
44 
45→ **Detailed guide:** [../server/prompts.md](../server/prompts.md)
46 
47### 4. Widget (Tool + UI)
48A **tool that returns visual UI**. Same as a tool but renders a React component.
49 
50**Use for:** Browsing data, interactive selection, visual feedback
51 
52```typescript
53server.tool(
54  { name, schema, widget: { name: "widget-name" } },
55  async (input) => widget({ props: { data }, output: text("...") })
56);
57```
58 
59→ **Detailed guide:** [../widgets/basics.md](../widgets/basics.md)
60 
61---
62 
63## Decision Matrix
64 
65| Need | Use | Example |
66|------|-----|---------|
67| Backend action | Tool | send-email, create-user, fetch-data |
68| Read-only data | Resource | config, user-profile, api-docs |
69| Prompt template | Prompt | code-review, summarize, translate |
70| Visual UI | Widget Tool | search-results, calendar, dashboard |
71 
72---
73 
74## Tool vs Widget?
75 
76**Use a tool (no widget) when:**
77- Output is simple text or data
78- No visual representation helps
79- Quick conversational response
80 
81**Use a widget when:**
82- Browsing/comparing multiple items
83- Visual data improves understanding (charts, images)
84- Interactive selection is easier visually
85 
86**When in doubt:** Use a widget. It makes the experience better.
87 
88---
89 
90## Key Patterns
91 
92### 1. One tool = one capability
93❌ `manage-users` (too broad)
94✅ `create-user`, `delete-user`, `list-users`
95 
96### 2. Don't lazy-load
97Tool calls are expensive. Return all needed data upfront.
98 
99❌ `list-products` + `get-product-details` (two calls)
100✅ `list-products` returns full data including details
101 
102### 3. Widget handles its own state
103UI state (selections, filters) lives in the widget via `useState` or `setState`.
104 
105❌ `select-item` tool, `set-filter` tool
106✅ Widget manages internally
107 
108### 4. `exposeAsTool` defaults to `false`
109Widgets are not auto-registered as tools by default. When defining a custom tool with `widget: { name }`, omitting `exposeAsTool` (or leaving it `false`) is correct — the custom tool handles registration:
110 
111```typescript
112export const widgetMetadata: WidgetMetadata = {
113  description: "...",
114  props: z.object({...}),
115  // exposeAsTool defaults to false — correct for custom-tool pattern
116};
117```
118 
119---
120 
121## Next Steps
122 
123- Build your first tool: [quickstart.md](quickstart.md)
124- Deep dive on tools: [../server/tools.md](../server/tools.md)
125- Learn about widgets: [../widgets/basics.md](../widgets/basics.md)
126