0
# Type System Reference
1

2
Complete type definitions for the MCP protocol.
3

4
## Core Protocol Types
5

6
### JSON-RPC Base
7

8
```typescript { .api }
9
const JSONRPC_VERSION = '2.0';
10

11
type RequestId = string | number;
12
type ProgressToken = string | number;
13
type Cursor = string;
14

15
interface Request {
16
  method: string;
17
  params?: { _meta?: { progressToken?: ProgressToken; }; [key: string]: unknown; };
18
}
19

20
interface Notification {
21
  method: string;
22
  params?: { _meta?: Record<string, unknown>; [key: string]: unknown; };
23
}
24

25
interface Result {
26
  _meta?: Record<string, unknown>;
27
  [key: string]: unknown;
28
}
29

30
interface JSONRPCRequest extends Request { jsonrpc: '2.0'; id: RequestId; }
31
interface JSONRPCNotification extends Notification { jsonrpc: '2.0'; }
32
interface JSONRPCResponse { jsonrpc: '2.0'; id: RequestId; result: Result; }
33
interface JSONRPCError {
34
  jsonrpc: '2.0';
35
  id: RequestId;
36
  error: { code: number; message: string; data?: unknown; };
37
}
38

39
type JSONRPCMessage = JSONRPCRequest | JSONRPCNotification | JSONRPCResponse | JSONRPCError;
40
```
41

42
### Protocol Version
43

44
```typescript { .api }
45
const LATEST_PROTOCOL_VERSION = '2025-06-18';
46
const DEFAULT_NEGOTIATED_PROTOCOL_VERSION = '2025-03-26';
47
const SUPPORTED_PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05', '2024-10-07'];
48
```
49

50
### Error Codes
51

52
```typescript { .api }
53
enum ErrorCode {
54
  ConnectionClosed = -32000,
55
  RequestTimeout = -32001,
56
  ParseError = -32700,
57
  InvalidRequest = -32600,
58
  MethodNotFound = -32601,
59
  InvalidParams = -32602,
60
  InternalError = -32603
61
}
62

63
class McpError extends Error {
64
  code: number;
65
  data?: unknown;
66
  constructor(code: number, message: string, data?: unknown);
67
}
68
```
69

70
### Implementation Info
71

72
```typescript { .api }
73
interface Implementation {
74
  name: string;
75
  version: string;
76
}
77
```
78

79
### Capabilities
80

81
```typescript { .api }
82
interface ServerCapabilities {
83
  prompts?: { listChanged?: boolean; };
84
  resources?: { subscribe?: boolean; listChanged?: boolean; };
85
  tools?: { listChanged?: boolean; };
86
  logging?: {};
87
  completions?: {};
88
  sampling?: {};
89
  elicitation?: {};
90
}
91

92
interface ClientCapabilities {
93
  sampling?: {};
94
  elicitation?: {};
95
  roots?: { listChanged?: boolean; };
96
}
97
```
98

99
## Content Types
100

101
```typescript { .api }
102
interface TextContent {
103
  type: 'text';
104
  text: string;
105
  annotations?: { audience?: ('user' | 'assistant')[]; priority?: number; };
106
}
107

108
interface ImageContent {
109
  type: 'image';
110
  data: string;           // Base64 or data URI
111
  mimeType: string;
112
}
113

114
interface AudioContent {
115
  type: 'audio';
116
  data: string;           // Base64
117
  mimeType: string;
118
}
119

120
interface EmbeddedResource {
121
  type: 'resource';
122
  resource: { uri: string; mimeType?: string; text?: string; blob?: string; };
123
}
124

125
interface ResourceLink {
126
  type: 'resource_link';
127
  name: string;
128
  title?: string;
129
  uri: string;
130
  description?: string;
131
  mimeType?: string;
132
  icons?: Icon[];
133
  _meta?: Record<string, unknown>;
134
}
135

136
type ContentBlock = TextContent | ImageContent | AudioContent | EmbeddedResource | ResourceLink;
137
```
138

139
## Metadata Types
140

141
```typescript { .api }
142
interface Icon {
143
  src: string;
144
  mimeType?: string;
145
  sizes?: string[];       // WxH format (e.g., "48x48", "96x96") or "any"
146
}
147

148
interface Icons {
149
  icons?: Icon[];
150
}
151

152
interface BaseMetadata {
153
  name: string;           // Required: programmatic/logical identifier
154
  title?: string;         // Optional: human-readable display name
155
}
156
```
157

158
## Tool Types
159

160
```typescript { .api }
161
interface Tool extends BaseMetadata {
162
  name: string;
163
  inputSchema: JSONSchema;
164
  outputSchema?: JSONSchema;
165
  annotations?: ToolAnnotations;
166
  _meta?: Record<string, unknown>;
167
}
168

169
interface ToolAnnotations {
170
  audience?: ('user' | 'assistant')[];
171
  [key: string]: unknown;
172
}
173

174
interface CallToolResult {
175
  content: ContentBlock[];
176
  isError?: boolean;
177
  structuredContent?: Record<string, unknown>;
178
  _meta?: Record<string, unknown>;
179
}
180

181
interface ListToolsResult {
182
  tools: Tool[];
183
  nextCursor?: string;
184
}
185
```
186

187
## Resource Types
188

189
```typescript { .api }
190
interface Resource extends BaseMetadata {
191
  uri: string;
192
  name: string;
193
  mimeType?: string;
194
  _meta?: Record<string, unknown>;
195
}
196

197
interface ResourceTemplate extends BaseMetadata {
198
  uriTemplate: string;
199
  name: string;
200
  mimeType?: string;
201
  _meta?: Record<string, unknown>;
202
}
203

204
interface TextResourceContents {
205
  uri: string;
206
  mimeType?: string;
207
  text: string;
208
}
209

210
interface BlobResourceContents {
211
  uri: string;
212
  mimeType?: string;
213
  blob: string;           // Base64 encoded
214
}
215

216
type ResourceContents = TextResourceContents | BlobResourceContents;
217

218
interface ReadResourceResult {
219
  contents: ResourceContents[];
220
  _meta?: Record<string, unknown>;
221
}
222

223
interface ListResourcesResult {
224
  resources: Resource[];
225
  nextCursor?: string;
226
}
227

228
interface ListResourceTemplatesResult {
229
  resourceTemplates: ResourceTemplate[];
230
  nextCursor?: string;
231
}
232
```
233

234
## Prompt Types
235

236
```typescript { .api }
237
interface Prompt extends BaseMetadata {
238
  name: string;
239
  arguments?: PromptArgument[];
240
  _meta?: Record<string, unknown>;
241
}
242

243
interface PromptArgument {
244
  name: string;
245
  description?: string;
246
  required?: boolean;
247
}
248

249
interface PromptMessage {
250
  role: 'user' | 'assistant';
251
  content: TextContent | ImageContent | AudioContent | EmbeddedResource;
252
}
253

254
interface GetPromptResult {
255
  description?: string;
256
  messages: PromptMessage[];
257
  _meta?: Record<string, unknown>;
258
}
259

260
interface ListPromptsResult {
261
  prompts: Prompt[];
262
  nextCursor?: string;
263
}
264
```
265

266
## Sampling Types
267

268
```typescript { .api }
269
interface SamplingMessage {
270
  role: 'user' | 'assistant';
271
  content: TextContent | ImageContent | AudioContent;
272
}
273

274
interface ModelHint {
275
  name?: string;
276
}
277

278
interface ModelPreferences {
279
  hints?: ModelHint[];
280
  costPriority?: number;            // 0-1
281
  speedPriority?: number;           // 0-1
282
  intelligencePriority?: number;    // 0-1
283
}
284

285
interface CreateMessageResult {
286
  role: 'assistant';
287
  content: TextContent | ImageContent | AudioContent;
288
  model: string;
289
  stopReason?: 'endTurn' | 'stopSequence' | 'maxTokens';
290
  _meta?: Record<string, unknown>;
291
}
292
```
293

294
## Elicitation Types
295

296
```typescript { .api }
297
interface ElicitResult {
298
  action: 'accept' | 'decline' | 'cancel';
299
  content?: Record<string, unknown>;
300
  _meta?: Record<string, unknown>;
301
}
302
```
303

304
## Completion Types
305

306
```typescript { .api }
307
interface PromptReference {
308
  type: 'ref/prompt';
309
  name: string;
310
}
311

312
interface ResourceTemplateReference {
313
  type: 'ref/resource';
314
  uri: string;
315
}
316

317
interface CompleteResult {
318
  completion: { values: string[]; total?: number; hasMore?: boolean; };
319
  _meta?: Record<string, unknown>;
320
}
321
```
322

323
## Logging Types
324

325
```typescript { .api }
326
type LoggingLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
327
```
328

329
## Root Types
330

331
```typescript { .api }
332
interface Root {
333
  uri: string;
334
  name: string;
335
}
336

337
interface ListRootsResult {
338
  roots: Root[];
339
  _meta?: Record<string, unknown>;
340
}
341
```
342

343
## Progress and Cancellation
344

345
```typescript { .api }
346
interface Progress {
347
  progress: number;
348
  total?: number;
349
}
350

351
interface ProgressNotification {
352
  method: 'notifications/progress';
353
  params: { progressToken: ProgressToken; progress: number; total?: number; };
354
}
355

356
interface CancelledNotification {
357
  method: 'notifications/cancelled';
358
  params: { requestId: RequestId; reason?: string; };
359
}
360
```
361

362
## Utility Types
363

364
```typescript { .api }
365
interface PaginatedRequest {
366
  cursor?: string;
367
}
368

369
interface PaginatedResult {
370
  nextCursor?: string;
371
}
372

373
type EmptyResult = Record<string, never>;
374

375
interface RequestInfo {
376
  headers?: Record<string, string | string[]>;
377
}
378

379
interface AuthInfo {
380
  token: string;
381
  clientId: string;
382
  scopes: string[];
383
  userId?: string;
384
  expiresAt?: number;
385
}
386

387
interface RequestMeta {
388
  progressToken?: ProgressToken;
389
  [key: string]: unknown;
390
}
391

392
type FetchLike = (url: string | URL, init?: RequestInit) => Promise<Response>;
393

394
interface TransportSendOptions {
395
  priority?: number;
396
  [key: string]: unknown;
397
}
398

399
interface JSONSchema {
400
  type?: string | string[];
401
  properties?: Record<string, JSONSchema>;
402
  items?: JSONSchema | JSONSchema[];
403
  required?: string[];
404
  enum?: unknown[];
405
  enumNames?: string[];
406
  const?: unknown;
407
  title?: string;
408
  description?: string;
409
  default?: unknown;
410
  examples?: unknown[];
411
  [key: string]: unknown;
412
}
413
```
414

415
## Type Guards
416

417
```typescript { .api }
418
function isJSONRPCRequest(value: unknown): value is JSONRPCRequest;
419
function isJSONRPCNotification(value: unknown): value is JSONRPCNotification;
420
function isJSONRPCResponse(value: unknown): value is JSONRPCResponse;
421
function isJSONRPCError(value: unknown): value is JSONRPCError;
422
```
423