0
# Server Prompts API
1

2
Prompts are reusable conversation templates for LLM interactions. Designed to be user-driven (e.g., slash commands, conversation starters).
3

4
## Registration
5

6
```typescript { .api }
7
server.registerPrompt<Args extends PromptArgsRawShape>(
8
  name: string,
9
  config: {
10
    title?: string;
11
    description?: string;
12
    argsSchema?: Args;
13
    icons?: Icons;
14
    _meta?: Record<string, unknown>;
15
  },
16
  callback: (args: z.infer<ZodObject<Args>>) => GetPromptResult | Promise<GetPromptResult>
17
): RegisteredPrompt;
18
```
19

20
## Examples
21

22
```typescript
23
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
24
import { z } from 'zod';
25

26
const server = new McpServer({ name: 'prompts-server', version: '1.0.0' });
27

28
// Simple prompt without arguments
29
server.registerPrompt('code-review', {
30
  title: 'Code Review',
31
  description: 'Review code for best practices'
32
}, () => ({
33
  messages: [{
34
    role: 'user',
35
    content: { type: 'text', text: 'Please review my code for best practices and potential issues.' }
36
  }]
37
}));
38

39
// Prompt with arguments
40
server.registerPrompt('analyze-file', {
41
  title: 'Analyze File',
42
  description: 'Analyze a specific file',
43
  argsSchema: {
44
    filePath: z.string().describe('Path to the file'),
45
    analysisType: z.enum(['security', 'performance', 'style']).describe('Type of analysis to perform')
46
  }
47
}, ({ filePath, analysisType }) => ({
48
  description: `Analyze ${filePath} for ${analysisType}`,
49
  messages: [{
50
    role: 'user',
51
    content: { type: 'text', text: `Please analyze ${filePath} focusing on ${analysisType} aspects.` }
52
  }]
53
}));
54

55
// Prompt with embedded resources
56
server.registerPrompt('review-code-with-context', {
57
  title: 'Code Review with Context',
58
  description: 'Review code with full context',
59
  argsSchema: {
60
    code: z.string().describe('Code to review')
61
  }
62
}, ({ code }) => ({
63
  messages: [
64
    { role: 'user', content: { type: 'text', text: 'Please review this code:' } },
65
    { role: 'user', content: { type: 'resource', resource: { uri: 'inline://code', mimeType: 'text/plain', text: code } } }
66
  ]
67
}));
68

69
// Multi-turn conversation
70
server.registerPrompt('interactive-review', {
71
  title: 'Interactive Code Review',
72
  description: 'Start an interactive code review session'
73
}, () => ({
74
  description: 'Interactive code review',
75
  messages: [
76
    { role: 'user', content: { type: 'text', text: 'I need help reviewing some code' } },
77
    { role: 'assistant', content: { type: 'text', text: 'I\'d be happy to help! Please share the code you\'d like me to review.' } }
78
  ]
79
}));
80
```
81

82
## Argument Completion
83

84
```typescript { .api }
85
import { completable } from '@modelcontextprotocol/sdk/server/completable.js';
86

87
// completable<T>(schema: ZodType<T>, completeCallback: CompleteCallback<T>): Completable<T>
88
type CompleteCallback<T> = (value: string, context?: { arguments?: Record<string, unknown> }) => Promise<string[]> | string[];
89
```
90

91
### Example
92

93
```typescript
94
server.registerPrompt('team-greeting', {
95
  title: 'Team Greeting',
96
  description: 'Generate a greeting for team members',
97
  argsSchema: {
98
    department: completable(z.string(), (value) => {
99
      return ['engineering', 'sales', 'marketing', 'support'].filter(d => d.startsWith(value));
100
    }),
101
    name: completable(z.string(), (value, context) => {
102
      // Provide name suggestions based on selected department
103
      const department = context?.arguments?.['department'];
104
      if (department === 'engineering') {
105
        return ['Alice', 'Bob', 'Charlie'].filter(n => n.startsWith(value));
106
      } else if (department === 'sales') {
107
        return ['David', 'Eve', 'Frank'].filter(n => n.startsWith(value));
108
      }
109
      return ['Guest'].filter(n => n.startsWith(value));
110
    })
111
  }
112
}, ({ department, name }) => ({
113
  messages: [{
114
    role: 'assistant',
115
    content: { type: 'text', text: `Hello ${name}, welcome to the ${department} team!` }
116
  }]
117
}));
118
```
119

120
## Return Values
121

122
```typescript { .api }
123
interface GetPromptResult {
124
  description?: string;
125
  messages: PromptMessage[];
126
  _meta?: Record<string, unknown>;
127
}
128

129
interface PromptMessage {
130
  role: 'user' | 'assistant';
131
  content: ContentBlock;  // TextContent | ImageContent | AudioContent | EmbeddedResource
132
}
133
```
134

135
### Examples
136

137
```typescript
138
// Simple text prompt
139
return {
140
  messages: [{ role: 'user', content: { type: 'text', text: 'Analyze this data for trends' } }]
141
};
142

143
// Prompt with image
144
return {
145
  messages: [{ role: 'user', content: { type: 'image', data: base64ImageData, mimeType: 'image/png' } }]
146
};
147

148
// Prompt with embedded resource
149
return {
150
  messages: [{
151
    role: 'user',
152
    content: {
153
      type: 'resource',
154
      resource: { uri: 'file:///project/README.md', mimeType: 'text/markdown', text: readmeContent }
155
    }
156
  }]
157
};
158
```
159

160
## Managing Prompts
161

162
```typescript { .api }
163
interface RegisteredPrompt {
164
  enable(): void;
165
  disable(): void;
166
  update(config: Partial<{ title?: string; description?: string; argsSchema?: PromptArgsRawShape; }>): void;
167
  remove(): void;
168
}
169
```
170

171
## Notifications
172

173
```typescript { .api }
174
server.sendPromptListChanged(): Promise<void>;
175
```
176

177
## Types Reference
178

179
```typescript { .api }
180
interface Prompt {
181
  name: string;
182
  title?: string;
183
  description?: string;
184
  arguments?: PromptArgument[];
185
  icons?: Icons;
186
  _meta?: Record<string, unknown>;
187
}
188

189
interface PromptArgument {
190
  name: string;
191
  description?: string;
192
  required?: boolean;
193
}
194

195
interface ListPromptsResult {
196
  prompts: Prompt[];
197
  nextCursor?: string;
198
}
199

200
type PromptArgsRawShape = Record<string, ZodTypeAny>;
201
```
202

203
## Legacy API
204

205
```typescript { .api }
206
server.prompt(name: string, callback: PromptCallback): RegisteredPrompt;
207
server.prompt(name: string, description: string, callback: PromptCallback): RegisteredPrompt;
208
server.prompt<Args extends PromptArgsRawShape>(name: string, argsSchema: Args, callback: PromptCallback<Args>): RegisteredPrompt;
209
server.prompt<Args extends PromptArgsRawShape>(name: string, description: string, argsSchema: Args, callback: PromptCallback<Args>): RegisteredPrompt;
210
```
211

212
Use `registerPrompt` for new code.
213