docs/api-reference/typescript/type-definitions.mdx

---
title: "TypeScript type definitions"
description: "TypeScript type system documentation"
---

## Core protocol types

### JSON-RPC types

```typescript
export const JSONRPC_VERSION = "2.0";

/** A uniquely identifying ID for a request in JSON-RPC */
export type RequestId = string | number;

/** A request that expects a response */
export interface JSONRPCRequest {
  jsonrpc: typeof JSONRPC_VERSION;
  id: RequestId;
  method: string;
  params?: Record<string, unknown>;
}

/** A notification which does not expect a response */
export interface JSONRPCNotification {
  jsonrpc: typeof JSONRPC_VERSION;
  method: string;
  params?: Record<string, unknown>;
}

/** A successful (non-error) response to a request */
export interface JSONRPCResponse {
  jsonrpc: typeof JSONRPC_VERSION;
  id: RequestId;
  result: unknown;
}

/** A response to a request that indicates an error occurred */
export interface JSONRPCError {
  jsonrpc: typeof JSONRPC_VERSION;
  id: RequestId;
  error: {
    code: number;
    message: string;
    data?: unknown;
  };
}

export type JSONRPCMessage = 
  | JSONRPCRequest 
  | JSONRPCNotification 
  | JSONRPCResponse 
  | JSONRPCError;
```

### Message content types

```typescript
/** Text provided to or from an LLM */
export interface TextContent {
  type: "text";
  text: string;
}

/** An image provided to or from an LLM */
export interface ImageContent {
  type: "image";
  data: string;  // Base64-encoded
  mimeType: string;
}

/** Describes a message issued to or received from an LLM API */
export interface SamplingMessage {
  role: "user" | "assistant";
  content: TextContent | ImageContent;
}

/** Progress information for long-running operations */
export interface Progress {
  progress: number;
  total?: number;
}

export type ProgressCallback = (progress: Progress) => void;
```

### Resource types

```typescript
/** The contents of a specific resource */
export interface ResourceContents {
  uri: string;
  mimeType?: string;
}

/** Text-based resource contents */
export interface TextResourceContents extends ResourceContents {
  text: string;
}

/** Binary resource contents */
export interface BlobResourceContents extends ResourceContents {
  blob: string;  // Base64-encoded
}

/** A known resource that the server is capable of reading */
export interface Resource {
  uri: string;
  name: string;
  description?: string;
  mimeType?: string;
}

/** A template description for resources available on the server */
export interface ResourceTemplate {
  uriTemplate: string;
  name: string;
  description?: string;
  mimeType?: string;
}
```

### Tool types

```typescript
/** Definition for a tool the client can call */
export interface Tool {
  name: string;
  description?: string;
  inputSchema: {
    type: "object";
    properties?: Record<string, unknown>;
  };
}
```

### Prompt types

```typescript
/** Describes an argument that a prompt can accept */
export interface PromptArgument {
  name: string;
  description?: string;
  required?: boolean;
}

/** A prompt or prompt template that the server offers */
export interface Prompt {
  name: string;
  description?: string;
  arguments?: PromptArgument[];
}
```

## Request/response types

### Resource requests

```typescript
export interface ListResourcesRequest {
  method: "resources/list";
  params?: {
    cursor?: string;
  };
}

export interface ListResourcesResult {
  resources: Resource[];
  nextCursor?: string;
}

export interface ReadResourceRequest {
  method: "resources/read";
  params: {
    uri: string;
  };
}

export interface ReadResourceResult {
  contents: Array<TextResourceContents | BlobResourceContents>;
}

export interface SubscribeRequest {
  method: "resources/subscribe";
  params: {
    uri: string;
  };
}

export interface UnsubscribeRequest {
  method: "resources/unsubscribe";
  params: {
    uri: string;
  };
}
```

### Tool requests

```typescript
export interface ListToolsRequest {
  method: "tools/list";
  params?: {
    cursor?: string;
  };
}

export interface ListToolsResult {
  tools: Tool[];
  nextCursor?: string;
}

export interface CallToolRequest {
  method: "tools/call";
  params: {
    name: string;
    arguments?: Record<string, unknown>;
    _meta?: {
      progressToken?: string | number;
    };
  };
}

export interface CallToolResult {
  toolResult: unknown;
}
```

### Prompt requests

```typescript
export interface ListPromptsRequest {
  method: "prompts/list";
  params?: {
    cursor?: string;
  };
}

export interface ListPromptsResult {
  prompts: Prompt[];
  nextCursor?: string;
}

export interface GetPromptRequest {
  method: "prompts/get";
  params: {
    name: string;
    arguments?: Record<string, string>;
  };
}

export interface GetPromptResult {
  description?: string;
  messages: SamplingMessage[];
}
```

## Protocol types

### Implementation info

```typescript
export interface Implementation {
  name: string;
  version: string;
}
```

### Capability types

```typescript
export interface ResourceCapabilities {
  subscribe?: boolean;
  listChanged?: boolean;
}

export interface PromptCapabilities {
  listChanged?: boolean;
}

export interface ToolCapabilities {
  listChanged?: boolean;
}

export interface ServerCapabilities {
  experimental?: Record<string, unknown>;
  logging?: Record<string, unknown>;
  prompts?: PromptCapabilities;
  resources?: ResourceCapabilities;
  tools?: ToolCapabilities;
}

export interface ClientCapabilities {
  experimental?: Record<string, unknown>;
  sampling?: Record<string, unknown>;
}
```

### Notification types

```typescript
export interface ResourceUpdatedNotification {
  method: "notifications/resources/updated";
  params: {
    uri: string;
  };
}

export interface ProgressNotification {
  method: "notifications/progress";
  params: Progress & {
    progressToken: string | number;
  };
}

export interface LogMessageNotification {
  method: "notifications/message";
  params: {
    level: "debug" | "info" | "warning" | "error";
    logger?: string;
    data: unknown;
  };
}

export type ServerNotification =
  | ResourceUpdatedNotification
  | ProgressNotification
  | LogMessageNotification;
```

## Error types

```typescript
export enum ErrorCode {
  // SDK error codes
  ConnectionClosed = -1,

  // Standard JSON-RPC error codes
  ParseError = -32700,
  InvalidRequest = -32600,
  MethodNotFound = -32601,
  InvalidParams = -32602,
  InternalError = -32603,
}

export class McpError extends Error {
  constructor(
    public readonly code: number,
    message: string,
    public readonly data?: unknown
  ) {
    super(`MCP error ${code}: ${message}`);
  }
}
```

## Transport types

```typescript
export interface Transport {
  start(): Promise<void>;
  send(message: JSONRPCMessage): Promise<void>;
  close(): Promise<void>;
  onclose?: () => void;
  onerror?: (error: Error) => void;
  onmessage?: (message: JSONRPCMessage) => void;
}

export interface StdioServerParameters {
  command: string;
  args?: string[];
  env?: Record<string, string>;
}
```

## Usage examples

### Type guards

```typescript
function isTextContent(content: 
  TextContent | ImageContent
): content is TextContent {
  return content.type === "text";
}

function isResourceUpdatedNotification(
  notification: ServerNotification
): notification is ResourceUpdatedNotification {
  return notification.method === "notifications/resources/updated";
}
```

### Type assertions

```typescript
function assertResource(data: unknown): asserts data is Resource {
  if (typeof data !== "object" || data === null) {
    throw new TypeError("Expected object");
  }

  const resource = data as Partial<Resource>;
  if (typeof resource.uri !== "string") {
    throw new TypeError("Expected string uri");
  }
  if (typeof resource.name !== "string") {
    throw new TypeError("Expected string name");
  }
}
```

### Using generics

```typescript
async function handleResourceContent<T extends ResourceContents>(
  content: T
): Promise<string> {
  if ("text" in content) {
    return content.text;
  }
  if ("blob" in content) {
    return atob(content.blob);
  }
  throw new Error("Invalid resource content");
}
```

### Working with union types

```typescript
function processMessage(message: SamplingMessage): string {
  const { content } = message;
  switch (content.type) {
    case "text":
      return content.text;
    case "image":
      return `Image: ${content.mimeType}`;
    default:
      const _exhaustiveCheck: never = content;
      throw new Error("Unknown content type");
  }
}
```

## Type utilities

```typescript
/** Helper type to extract request params from method name */
type RequestParams<T extends string> = Extract<
  ClientRequest,
  { method: T }
>["params"];

/** Helper type to extract result type from schema */
type SchemaType<T extends ZodType> = z.infer<T>;

/** Helper type for request handlers */
type RequestHandler<T extends ClientRequest> = (
  request: T
) => Promise<SchemaType<typeof ResultSchemas[T["method"]]>>;
```