Interface ToolContext

Context passed to tool handlers during execution.

Provides MCP-compliant mechanisms for:

Progress Reporting: Send incremental updates during long operations
Cancellation: Gracefully abort when client sends cancellation
Session Identity: Identify which client session invoked the tool

All features are sourced from the SDK's RequestHandlerExtra and mapped to this clean interface by the framework. Cancellation uses the SDK's native AbortSignal (per-request, automatically aborted on notifications/cancelled).

Example

defineTool({
  name: 'process-batch',
  description: 'Process items with progress',
  input: z.object({ items: z.array(z.string()) }),
  handler: async ({ items }, context) => {
    const total = items.length;

    for (let i = 0; i < items.length; i++) {
      // Check for cancellation (MCP notifications/cancelled)
      if (context.abortSignal.aborted) {
        return error(`Cancelled after ${i} items`);
      }

      // Report progress (MCP notifications/progress)
      await context.reportProgress?.({
        progress: i + 1,
        total,
        message: `Processing ${items[i]}...`
      });

      await processItem(items[i]);
    }

    return text(`Processed ${total} items`);
  },
});

interface ToolContext {
    abortSignal: AbortSignal;
    auth?: { authInfo: AuthInfo; extra?: Record<string, unknown> };
    createMessage?: (
        params:
            | CreateMessageRequestParamsBase
            | {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                includeContext?: "none"
                | "thisServer"
                | "allServers";
                maxTokens: number;
                messages: {
                    _meta?: { [key: string]: unknown };
                    content:
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: (...) | (...);
                                lastModified?: (...) | (...);
                                priority?: (...) | (...);
                            };
                            text: string;
                            type: "text";
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: (...) | (...);
                                lastModified?: (...) | (...);
                                priority?: (...) | (...);
                            };
                            data: string;
                            mimeType: string;
                            type: "image";
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            annotations?: {
                                audience?: (...) | (...);
                                lastModified?: (...) | (...);
                                priority?: (...) | (...);
                            };
                            data: string;
                            mimeType: string;
                            type: "audio";
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            id: string;
                            input: { [key: string]: unknown };
                            name: string;
                            type: "tool_use";
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            content: (
                                | { _meta?: ...; annotations?: ...; text: ...; type: ... }
                                | {
                                    _meta?: ...;
                                    annotations?: ...;
                                    data: ...;
                                    mimeType: ...;
                                    type: ...;
                                }
                                | {
                                    _meta?: ...;
                                    annotations?: ...;
                                    data: ...;
                                    mimeType: ...;
                                    type: ...;
                                }
                                | {
                                    _meta?: ...;
                                    annotations?: ...;
                                    description?: ...;
                                    icons?: ...;
                                    mimeType?: ...;
                                    name: ...;
                                    title?: ...;
                                    type: ...;
                                    uri: ...;
                                }
                                | { _meta?: ...; annotations?: ...; resource: ...; type: ... }
                            )[];
                            isError?: boolean;
                            structuredContent?: { [key: string]: unknown };
                            toolUseId: string;
                            type: "tool_result";
                        }
                        | (
                            | {
                                _meta?: (...)
                                | (...);
                                annotations?: (...) | (...);
                                text: string;
                                type: "text";
                            }
                            | {
                                _meta?: (...)
                                | (...);
                                annotations?: (...) | (...);
                                data: string;
                                mimeType: string;
                                type: "image";
                            }
                            | {
                                _meta?: (...)
                                | (...);
                                annotations?: (...) | (...);
                                data: string;
                                mimeType: string;
                                type: "audio";
                            }
                            | {
                                _meta?: (...)
                                | (...);
                                id: string;
                                input: { [key: ...]: ... };
                                name: string;
                                type: "tool_use";
                            }
                            | {
                                _meta?: (...)
                                | (...);
                                content: (...)[];
                                isError?: (...) | (...) | (...);
                                structuredContent?: (...) | (...);
                                toolUseId: string;
                                type: "tool_result";
                            }
                        )[];
                    role: "user"
                    | "assistant";
                }[];
                metadata?: object;
                modelPreferences?: {
                    costPriority?: number;
                    hints?: { name?: string }[];
                    intelligencePriority?: number;
                    speedPriority?: number;
                };
                stopSequences?: string[];
                systemPrompt?: string;
                task?: { ttl?: number };
                temperature?: number;
                toolChoice?: { mode?: "none" | "required" | "auto" };
                tools?: {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        destructiveHint?: boolean;
                        idempotentHint?: boolean;
                        openWorldHint?: boolean;
                        readOnlyHint?: boolean;
                        title?: string;
                    };
                    description?: string;
                    execution?: { taskSupport?: "optional"
                    | "required"
                    | "forbidden" };
                    icons?: {
                        mimeType?: (...) | (...);
                        sizes?: (...) | (...);
                        src: string;
                        theme?: (...) | (...) | (...);
                    }[];
                    inputSchema: {
                        properties?: { [key: string]: object };
                        required?: string[];
                        type: "object";
                        [key: string]: unknown;
                    };
                    name: string;
                    outputSchema?: {
                        properties?: { [key: ...]: ... };
                        required?: (...)[];
                        type: "object";
                        [key: string]: unknown;
                    };
                    title?: string;
                }[];
            },
    ) => | Promise<
        {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            content: | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: (...)[];
                    lastModified?: string;
                    priority?: number;
                };
                text: string;
                type: "text";
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: (...)[];
                    lastModified?: string;
                    priority?: number;
                };
                data: string;
                mimeType: string;
                type: "image";
            }
            | {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    audience?: (...)[];
                    lastModified?: string;
                    priority?: number;
                };
                data: string;
                mimeType: string;
                type: "audio";
            };
            model: string;
            role: "user"
            | "assistant";
            stopReason?: string;
            [key: string]: unknown;
        },
    >
    | undefined;
    elicitInput?: (
        params:
            | {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                message: string;
                mode?: "form";
                requestedSchema: {
                    properties: {
                        [key: string]: | {
                            default?: string;
                            description?: string;
                            enum: string[];
                            enumNames?: string[];
                            title?: string;
                            type: "string";
                        }
                        | {
                            default?: string;
                            description?: string;
                            enum: string[];
                            title?: string;
                            type: "string";
                        }
                        | {
                            default?: string;
                            description?: string;
                            oneOf: { const: string; title: string }[];
                            title?: string;
                            type: "string";
                        }
                        | {
                            default?: string[];
                            description?: string;
                            items: { enum: string[]; type: "string" };
                            maxItems?: number;
                            minItems?: number;
                            title?: string;
                            type: "array";
                        }
                        | {
                            default?: string[];
                            description?: string;
                            items: { anyOf: { const: ...; title: ... }[] };
                            maxItems?: number;
                            minItems?: number;
                            title?: string;
                            type: "array";
                        }
                        | {
                            default?: boolean;
                            description?: string;
                            title?: string;
                            type: "boolean";
                        }
                        | {
                            default?: string;
                            description?: string;
                            format?: "email"
                            | "uri"
                            | "date"
                            | "date-time";
                            maxLength?: number;
                            minLength?: number;
                            title?: string;
                            type: "string";
                        }
                        | {
                            default?: number;
                            description?: string;
                            maximum?: number;
                            minimum?: number;
                            title?: string;
                            type: "number"
                            | "integer";
                        };
                    };
                    required?: string[];
                    type: "object";
                };
                task?: { ttl?: number };
            }
            | {
                _meta?: {
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    progressToken?: string | number;
                    [key: string]: unknown;
                };
                elicitationId: string;
                message: string;
                mode: "url";
                task?: { ttl?: number };
                url: string;
            },
    ) => | Promise<
        {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            action: "cancel"
            | "accept"
            | "decline";
            content?: { [key: string]: string | number | boolean | string[] };
            [key: string]: unknown;
        },
    >
    | undefined;
    listRoots?: () => Promise<
        {
            roots: {
                _meta?: { [key: string]: unknown };
                name?: string;
                uri: string;
            }[];
        },
    >;
    reportProgress?: ProgressReporter;
    requestId: string
    | number;
    sessionId?: string;
    stateless: boolean;
}

Hierarchy (View Summary)

ToolContext
- TaskCreateContext
- TaskOperationContext

Index

Properties

abortSignal auth? createMessage? elicitInput? listRoots? reportProgress? requestId sessionId? stateless

Properties

`Readonly`abortSignal

abortSignal: AbortSignal

AbortSignal that triggers when the request is cancelled.

MCP Protocol: Triggered when client sends notifications/cancelled with a matching requestId. This is the SDK's native AbortSignal, created per-request and managed by the MCP protocol layer.

Tools SHOULD check this signal periodically during long-running operations and abort gracefully when triggered.

Example

// Check before expensive operations
if (context.abortSignal.aborted) {
  throw new Error('Operation cancelled');
}

// Pass signal to fetch/other APIs that support it
const response = await fetch(url, { signal: context.abortSignal });

`Optional` `Readonly`auth

auth?: { authInfo: AuthInfo; extra?: Record<string, unknown> }

Authentication context for the current request.

Available when auth middleware is configured on the server. Contains the verified token info (authInfo) and optional consumer-provided data (extra) from the onAuthenticated hook.

undefined when no auth is configured (anonymous access).

Type Declaration

ReadonlyauthInfo: AuthInfo
Verified auth info from the Bearer token
Optional Readonlyextra?: Record<string, unknown>
Consumer-provided extra data from onAuthenticated hook

Example

handler: async (args, ctx) => {
  if (ctx.auth) {
    const { clientId, scopes } = ctx.auth.authInfo;
    const role = ctx.auth.extra?.role;
  }
  return text('OK');
}

`Optional` `Readonly`createMessage

createMessage?: (
    params:
        | CreateMessageRequestParamsBase
        | {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            includeContext?: "none"
            | "thisServer"
            | "allServers";
            maxTokens: number;
            messages: {
                _meta?: { [key: string]: unknown };
                content:
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: (...) | (...);
                            lastModified?: (...) | (...);
                            priority?: (...) | (...);
                        };
                        text: string;
                        type: "text";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: (...) | (...);
                            lastModified?: (...) | (...);
                            priority?: (...) | (...);
                        };
                        data: string;
                        mimeType: string;
                        type: "image";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: (...) | (...);
                            lastModified?: (...) | (...);
                            priority?: (...) | (...);
                        };
                        data: string;
                        mimeType: string;
                        type: "audio";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        id: string;
                        input: { [key: string]: unknown };
                        name: string;
                        type: "tool_use";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        content: (
                            | { _meta?: ...; annotations?: ...; text: ...; type: ... }
                            | {
                                _meta?: ...;
                                annotations?: ...;
                                data: ...;
                                mimeType: ...;
                                type: ...;
                            }
                            | {
                                _meta?: ...;
                                annotations?: ...;
                                data: ...;
                                mimeType: ...;
                                type: ...;
                            }
                            | {
                                _meta?: ...;
                                annotations?: ...;
                                description?: ...;
                                icons?: ...;
                                mimeType?: ...;
                                name: ...;
                                title?: ...;
                                type: ...;
                                uri: ...;
                            }
                            | { _meta?: ...; annotations?: ...; resource: ...; type: ... }
                        )[];
                        isError?: boolean;
                        structuredContent?: { [key: string]: unknown };
                        toolUseId: string;
                        type: "tool_result";
                    }
                    | (
                        | {
                            _meta?: (...)
                            | (...);
                            annotations?: (...) | (...);
                            text: string;
                            type: "text";
                        }
                        | {
                            _meta?: (...)
                            | (...);
                            annotations?: (...) | (...);
                            data: string;
                            mimeType: string;
                            type: "image";
                        }
                        | {
                            _meta?: (...)
                            | (...);
                            annotations?: (...) | (...);
                            data: string;
                            mimeType: string;
                            type: "audio";
                        }
                        | {
                            _meta?: (...)
                            | (...);
                            id: string;
                            input: { [key: ...]: ... };
                            name: string;
                            type: "tool_use";
                        }
                        | {
                            _meta?: (...)
                            | (...);
                            content: (...)[];
                            isError?: (...) | (...) | (...);
                            structuredContent?: (...) | (...);
                            toolUseId: string;
                            type: "tool_result";
                        }
                    )[];
                role: "user"
                | "assistant";
            }[];
            metadata?: object;
            modelPreferences?: {
                costPriority?: number;
                hints?: { name?: string }[];
                intelligencePriority?: number;
                speedPriority?: number;
            };
            stopSequences?: string[];
            systemPrompt?: string;
            task?: { ttl?: number };
            temperature?: number;
            toolChoice?: { mode?: "none" | "required" | "auto" };
            tools?: {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    destructiveHint?: boolean;
                    idempotentHint?: boolean;
                    openWorldHint?: boolean;
                    readOnlyHint?: boolean;
                    title?: string;
                };
                description?: string;
                execution?: { taskSupport?: "optional"
                | "required"
                | "forbidden" };
                icons?: {
                    mimeType?: (...) | (...);
                    sizes?: (...) | (...);
                    src: string;
                    theme?: (...) | (...) | (...);
                }[];
                inputSchema: {
                    properties?: { [key: string]: object };
                    required?: string[];
                    type: "object";
                    [key: string]: unknown;
                };
                name: string;
                outputSchema?: {
                    properties?: { [key: ...]: ... };
                    required?: (...)[];
                    type: "object";
                    [key: string]: unknown;
                };
                title?: string;
            }[];
        },
) => | Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        content: | {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: (...)[];
                lastModified?: string;
                priority?: number;
            };
            text: string;
            type: "text";
        }
        | {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: (...)[];
                lastModified?: string;
                priority?: number;
            };
            data: string;
            mimeType: string;
            type: "image";
        }
        | {
            _meta?: { [key: string]: unknown };
            annotations?: {
                audience?: (...)[];
                lastModified?: string;
                priority?: number;
            };
            data: string;
            mimeType: string;
            type: "audio";
        };
        model: string;
        role: "user"
        | "assistant";
        stopReason?: string;
        [key: string]: unknown;
    },
>
| undefined

Request LLM sampling from the client.

MCP Protocol: Sends a sampling/createMessage request to the client, which returns an LLM-generated response. This enables server-initiated LLM interactions (e.g., asking the LLM to summarize data for the user).

Availability: Only present when the client declares sampling capability AND the session is stateful. In stateless mode or when the client doesn't support sampling, this will be undefined.

Type Declaration

- (
      params:
          | CreateMessageRequestParamsBase
          | {
              _meta?: {
                  "io.modelcontextprotocol/related-task"?: { taskId: string };
                  progressToken?: string | number;
                  [key: string]: unknown;
              };
              includeContext?: "none"
              | "thisServer"
              | "allServers";
              maxTokens: number;
              messages: {
                  _meta?: { [key: string]: unknown };
                  content:
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: (...) | (...);
                              lastModified?: (...) | (...);
                              priority?: (...) | (...);
                          };
                          text: string;
                          type: "text";
                      }
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: (...) | (...);
                              lastModified?: (...) | (...);
                              priority?: (...) | (...);
                          };
                          data: string;
                          mimeType: string;
                          type: "image";
                      }
                      | {
                          _meta?: { [key: string]: unknown };
                          annotations?: {
                              audience?: (...) | (...);
                              lastModified?: (...) | (...);
                              priority?: (...) | (...);
                          };
                          data: string;
                          mimeType: string;
                          type: "audio";
                      }
                      | {
                          _meta?: { [key: string]: unknown };
                          id: string;
                          input: { [key: string]: unknown };
                          name: string;
                          type: "tool_use";
                      }
                      | {
                          _meta?: { [key: string]: unknown };
                          content: (
                              | { _meta?: ...; annotations?: ...; text: ...; type: ... }
                              | {
                                  _meta?: ...;
                                  annotations?: ...;
                                  data: ...;
                                  mimeType: ...;
                                  type: ...;
                              }
                              | {
                                  _meta?: ...;
                                  annotations?: ...;
                                  data: ...;
                                  mimeType: ...;
                                  type: ...;
                              }
                              | {
                                  _meta?: ...;
                                  annotations?: ...;
                                  description?: ...;
                                  icons?: ...;
                                  mimeType?: ...;
                                  name: ...;
                                  title?: ...;
                                  type: ...;
                                  uri: ...;
                              }
                              | { _meta?: ...; annotations?: ...; resource: ...; type: ... }
                          )[];
                          isError?: boolean;
                          structuredContent?: { [key: string]: unknown };
                          toolUseId: string;
                          type: "tool_result";
                      }
                      | (
                          | {
                              _meta?: (...)
                              | (...);
                              annotations?: (...) | (...);
                              text: string;
                              type: "text";
                          }
                          | {
                              _meta?: (...)
                              | (...);
                              annotations?: (...) | (...);
                              data: string;
                              mimeType: string;
                              type: "image";
                          }
                          | {
                              _meta?: (...)
                              | (...);
                              annotations?: (...) | (...);
                              data: string;
                              mimeType: string;
                              type: "audio";
                          }
                          | {
                              _meta?: (...)
                              | (...);
                              id: string;
                              input: { [key: ...]: ... };
                              name: string;
                              type: "tool_use";
                          }
                          | {
                              _meta?: (...)
                              | (...);
                              content: (...)[];
                              isError?: (...) | (...) | (...);
                              structuredContent?: (...) | (...);
                              toolUseId: string;
                              type: "tool_result";
                          }
                      )[];
                  role: "user"
                  | "assistant";
              }[];
              metadata?: object;
              modelPreferences?: {
                  costPriority?: number;
                  hints?: { name?: string }[];
                  intelligencePriority?: number;
                  speedPriority?: number;
              };
              stopSequences?: string[];
              systemPrompt?: string;
              task?: { ttl?: number };
              temperature?: number;
              toolChoice?: { mode?: "none" | "required" | "auto" };
              tools?: {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      destructiveHint?: boolean;
                      idempotentHint?: boolean;
                      openWorldHint?: boolean;
                      readOnlyHint?: boolean;
                      title?: string;
                  };
                  description?: string;
                  execution?: { taskSupport?: "optional"
                  | "required"
                  | "forbidden" };
                  icons?: {
                      mimeType?: (...) | (...);
                      sizes?: (...) | (...);
                      src: string;
                      theme?: (...) | (...) | (...);
                  }[];
                  inputSchema: {
                      properties?: { [key: string]: object };
                      required?: string[];
                      type: "object";
                      [key: string]: unknown;
                  };
                  name: string;
                  outputSchema?: {
                      properties?: { [key: ...]: ... };
                      required?: (...)[];
                      type: "object";
                      [key: string]: unknown;
                  };
                  title?: string;
              }[];
          },
  ): | Promise<
      {
          _meta?: {
              "io.modelcontextprotocol/related-task"?: { taskId: string };
              progressToken?: string | number;
              [key: string]: unknown;
          };
          content: | {
              _meta?: { [key: string]: unknown };
              annotations?: {
                  audience?: (...)[];
                  lastModified?: string;
                  priority?: number;
              };
              text: string;
              type: "text";
          }
          | {
              _meta?: { [key: string]: unknown };
              annotations?: {
                  audience?: (...)[];
                  lastModified?: string;
                  priority?: number;
              };
              data: string;
              mimeType: string;
              type: "image";
          }
          | {
              _meta?: { [key: string]: unknown };
              annotations?: {
                  audience?: (...)[];
                  lastModified?: string;
                  priority?: number;
              };
              data: string;
              mimeType: string;
              type: "audio";
          };
          model: string;
          role: "user"
          | "assistant";
          stopReason?: string;
          [key: string]: unknown;
      },
  >
  | undefined
- Parameters
  - params:
        | CreateMessageRequestParamsBase
        | {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            includeContext?: "none"
            | "thisServer"
            | "allServers";
            maxTokens: number;
            messages: {
                _meta?: { [key: string]: unknown };
                content:
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: (...) | (...);
                            lastModified?: (...) | (...);
                            priority?: (...) | (...);
                        };
                        text: string;
                        type: "text";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: (...) | (...);
                            lastModified?: (...) | (...);
                            priority?: (...) | (...);
                        };
                        data: string;
                        mimeType: string;
                        type: "image";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: (...) | (...);
                            lastModified?: (...) | (...);
                            priority?: (...) | (...);
                        };
                        data: string;
                        mimeType: string;
                        type: "audio";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        id: string;
                        input: { [key: string]: unknown };
                        name: string;
                        type: "tool_use";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        content: (
                            | { _meta?: ...; annotations?: ...; text: ...; type: ... }
                            | {
                                _meta?: ...;
                                annotations?: ...;
                                data: ...;
                                mimeType: ...;
                                type: ...;
                            }
                            | {
                                _meta?: ...;
                                annotations?: ...;
                                data: ...;
                                mimeType: ...;
                                type: ...;
                            }
                            | {
                                _meta?: ...;
                                annotations?: ...;
                                description?: ...;
                                icons?: ...;
                                mimeType?: ...;
                                name: ...;
                                title?: ...;
                                type: ...;
                                uri: ...;
                            }
                            | { _meta?: ...; annotations?: ...; resource: ...; type: ... }
                        )[];
                        isError?: boolean;
                        structuredContent?: { [key: string]: unknown };
                        toolUseId: string;
                        type: "tool_result";
                    }
                    | (
                        | {
                            _meta?: (...)
                            | (...);
                            annotations?: (...) | (...);
                            text: string;
                            type: "text";
                        }
                        | {
                            _meta?: (...)
                            | (...);
                            annotations?: (...) | (...);
                            data: string;
                            mimeType: string;
                            type: "image";
                        }
                        | {
                            _meta?: (...)
                            | (...);
                            annotations?: (...) | (...);
                            data: string;
                            mimeType: string;
                            type: "audio";
                        }
                        | {
                            _meta?: (...)
                            | (...);
                            id: string;
                            input: { [key: ...]: ... };
                            name: string;
                            type: "tool_use";
                        }
                        | {
                            _meta?: (...)
                            | (...);
                            content: (...)[];
                            isError?: (...) | (...) | (...);
                            structuredContent?: (...) | (...);
                            toolUseId: string;
                            type: "tool_result";
                        }
                    )[];
                role: "user"
                | "assistant";
            }[];
            metadata?: object;
            modelPreferences?: {
                costPriority?: number;
                hints?: { name?: string }[];
                intelligencePriority?: number;
                speedPriority?: number;
            };
            stopSequences?: string[];
            systemPrompt?: string;
            task?: { ttl?: number };
            temperature?: number;
            toolChoice?: { mode?: "none" | "required" | "auto" };
            tools?: {
                _meta?: { [key: string]: unknown };
                annotations?: {
                    destructiveHint?: boolean;
                    idempotentHint?: boolean;
                    openWorldHint?: boolean;
                    readOnlyHint?: boolean;
                    title?: string;
                };
                description?: string;
                execution?: { taskSupport?: "optional"
                | "required"
                | "forbidden" };
                icons?: {
                    mimeType?: (...) | (...);
                    sizes?: (...) | (...);
                    src: string;
                    theme?: (...) | (...) | (...);
                }[];
                inputSchema: {
                    properties?: { [key: string]: object };
                    required?: string[];
                    type: "object";
                    [key: string]: unknown;
                };
                name: string;
                outputSchema?: {
                    properties?: { [key: ...]: ... };
                    required?: (...)[];
                    type: "object";
                    [key: string]: unknown;
                };
                title?: string;
            }[];
        }
    Sampling request parameters (messages, model preferences, etc.)
  Returns
      | Promise<
          {
              _meta?: {
                  "io.modelcontextprotocol/related-task"?: { taskId: string };
                  progressToken?: string | number;
                  [key: string]: unknown;
              };
              content: | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: (...)[];
                      lastModified?: string;
                      priority?: number;
                  };
                  text: string;
                  type: "text";
              }
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: (...)[];
                      lastModified?: string;
                      priority?: number;
                  };
                  data: string;
                  mimeType: string;
                  type: "image";
              }
              | {
                  _meta?: { [key: string]: unknown };
                  annotations?: {
                      audience?: (...)[];
                      lastModified?: string;
                      priority?: number;
                  };
                  data: string;
                  mimeType: string;
                  type: "audio";
              };
              model: string;
              role: "user"
              | "assistant";
              stopReason?: string;
              [key: string]: unknown;
          },
      >
      | undefined
  The LLM's response with model info and stop reason

Example

if (context.createMessage) {
  const result = await context.createMessage({
    messages: [{ role: 'user', content: { type: 'text', text: 'Summarize this data' } }],
    maxTokens: 500,
  });
  // result.content, result.model, result.stopReason
}

`Optional` `Readonly`elicitInput

elicitInput?: (
    params:
        | {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            message: string;
            mode?: "form";
            requestedSchema: {
                properties: {
                    [key: string]: | {
                        default?: string;
                        description?: string;
                        enum: string[];
                        enumNames?: string[];
                        title?: string;
                        type: "string";
                    }
                    | {
                        default?: string;
                        description?: string;
                        enum: string[];
                        title?: string;
                        type: "string";
                    }
                    | {
                        default?: string;
                        description?: string;
                        oneOf: { const: string; title: string }[];
                        title?: string;
                        type: "string";
                    }
                    | {
                        default?: string[];
                        description?: string;
                        items: { enum: string[]; type: "string" };
                        maxItems?: number;
                        minItems?: number;
                        title?: string;
                        type: "array";
                    }
                    | {
                        default?: string[];
                        description?: string;
                        items: { anyOf: { const: ...; title: ... }[] };
                        maxItems?: number;
                        minItems?: number;
                        title?: string;
                        type: "array";
                    }
                    | {
                        default?: boolean;
                        description?: string;
                        title?: string;
                        type: "boolean";
                    }
                    | {
                        default?: string;
                        description?: string;
                        format?: "email"
                        | "uri"
                        | "date"
                        | "date-time";
                        maxLength?: number;
                        minLength?: number;
                        title?: string;
                        type: "string";
                    }
                    | {
                        default?: number;
                        description?: string;
                        maximum?: number;
                        minimum?: number;
                        title?: string;
                        type: "number"
                        | "integer";
                    };
                };
                required?: string[];
                type: "object";
            };
            task?: { ttl?: number };
        }
        | {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            elicitationId: string;
            message: string;
            mode: "url";
            task?: { ttl?: number };
            url: string;
        },
) => | Promise<
    {
        _meta?: {
            "io.modelcontextprotocol/related-task"?: { taskId: string };
            progressToken?: string | number;
            [key: string]: unknown;
        };
        action: "cancel"
        | "accept"
        | "decline";
        content?: { [key: string]: string | number | boolean | string[] };
        [key: string]: unknown;
    },
>
| undefined

Request user input via the client's elicitation UI.

MCP Protocol: Sends an elicitation/create request to the client, which presents a form or URL to the user and returns their input.

Availability: Only present when the client declares elicitation capability AND the session is stateful. In stateless mode or when the client doesn't support elicitation, this will be undefined.

Type Declaration

- (
      params:
          | {
              _meta?: {
                  "io.modelcontextprotocol/related-task"?: { taskId: string };
                  progressToken?: string | number;
                  [key: string]: unknown;
              };
              message: string;
              mode?: "form";
              requestedSchema: {
                  properties: {
                      [key: string]: | {
                          default?: string;
                          description?: string;
                          enum: string[];
                          enumNames?: string[];
                          title?: string;
                          type: "string";
                      }
                      | {
                          default?: string;
                          description?: string;
                          enum: string[];
                          title?: string;
                          type: "string";
                      }
                      | {
                          default?: string;
                          description?: string;
                          oneOf: { const: string; title: string }[];
                          title?: string;
                          type: "string";
                      }
                      | {
                          default?: string[];
                          description?: string;
                          items: { enum: string[]; type: "string" };
                          maxItems?: number;
                          minItems?: number;
                          title?: string;
                          type: "array";
                      }
                      | {
                          default?: string[];
                          description?: string;
                          items: { anyOf: { const: ...; title: ... }[] };
                          maxItems?: number;
                          minItems?: number;
                          title?: string;
                          type: "array";
                      }
                      | {
                          default?: boolean;
                          description?: string;
                          title?: string;
                          type: "boolean";
                      }
                      | {
                          default?: string;
                          description?: string;
                          format?: "email"
                          | "uri"
                          | "date"
                          | "date-time";
                          maxLength?: number;
                          minLength?: number;
                          title?: string;
                          type: "string";
                      }
                      | {
                          default?: number;
                          description?: string;
                          maximum?: number;
                          minimum?: number;
                          title?: string;
                          type: "number"
                          | "integer";
                      };
                  };
                  required?: string[];
                  type: "object";
              };
              task?: { ttl?: number };
          }
          | {
              _meta?: {
                  "io.modelcontextprotocol/related-task"?: { taskId: string };
                  progressToken?: string | number;
                  [key: string]: unknown;
              };
              elicitationId: string;
              message: string;
              mode: "url";
              task?: { ttl?: number };
              url: string;
          },
  ): | Promise<
      {
          _meta?: {
              "io.modelcontextprotocol/related-task"?: { taskId: string };
              progressToken?: string | number;
              [key: string]: unknown;
          };
          action: "cancel"
          | "accept"
          | "decline";
          content?: { [key: string]: string | number | boolean | string[] };
          [key: string]: unknown;
      },
  >
  | undefined
- Parameters
  - params:
        | {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            message: string;
            mode?: "form";
            requestedSchema: {
                properties: {
                    [key: string]: | {
                        default?: string;
                        description?: string;
                        enum: string[];
                        enumNames?: string[];
                        title?: string;
                        type: "string";
                    }
                    | {
                        default?: string;
                        description?: string;
                        enum: string[];
                        title?: string;
                        type: "string";
                    }
                    | {
                        default?: string;
                        description?: string;
                        oneOf: { const: string; title: string }[];
                        title?: string;
                        type: "string";
                    }
                    | {
                        default?: string[];
                        description?: string;
                        items: { enum: string[]; type: "string" };
                        maxItems?: number;
                        minItems?: number;
                        title?: string;
                        type: "array";
                    }
                    | {
                        default?: string[];
                        description?: string;
                        items: { anyOf: { const: ...; title: ... }[] };
                        maxItems?: number;
                        minItems?: number;
                        title?: string;
                        type: "array";
                    }
                    | {
                        default?: boolean;
                        description?: string;
                        title?: string;
                        type: "boolean";
                    }
                    | {
                        default?: string;
                        description?: string;
                        format?: "email"
                        | "uri"
                        | "date"
                        | "date-time";
                        maxLength?: number;
                        minLength?: number;
                        title?: string;
                        type: "string";
                    }
                    | {
                        default?: number;
                        description?: string;
                        maximum?: number;
                        minimum?: number;
                        title?: string;
                        type: "number"
                        | "integer";
                    };
                };
                required?: string[];
                type: "object";
            };
            task?: { ttl?: number };
        }
        | {
            _meta?: {
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                progressToken?: string | number;
                [key: string]: unknown;
            };
            elicitationId: string;
            message: string;
            mode: "url";
            task?: { ttl?: number };
            url: string;
        }
    Elicitation parameters (form schema or URL)
  Returns
      | Promise<
          {
              _meta?: {
                  "io.modelcontextprotocol/related-task"?: { taskId: string };
                  progressToken?: string | number;
                  [key: string]: unknown;
              };
              action: "cancel"
              | "accept"
              | "decline";
              content?: { [key: string]: string | number | boolean | string[] };
              [key: string]: unknown;
          },
      >
      | undefined
  User's response (accept/decline/cancel with optional content)

Example

if (context.elicitInput) {
  const result = await context.elicitInput({
    message: 'Please confirm the deployment target',
    requestedSchema: {
      type: 'object',
      properties: {
        confirmed: { type: 'boolean', title: 'Confirm deployment' },
      },
    },
  });
  if (result.action === 'accept') {
    // result.content contains the form values
  }
}

`Optional` `Readonly`listRoots

listRoots?: () => Promise<
    {
        roots: {
            _meta?: { [key: string]: unknown };
            name?: string;
            uri: string;
        }[];
    },
>

List the client's root URIs.

MCP Protocol: Sends a roots/list request to the client, which returns the set of root URIs (workspace folders, project roots, etc.) the client has made available to the server.

Availability: Only present when the client declares roots capability AND the session is stateful. In stateless mode or when the client doesn't support roots, this will be undefined.

Type Declaration

- (): Promise<
      {
          roots: {
              _meta?: { [key: string]: unknown };
              name?: string;
              uri: string;
          }[];
      },
  >
- Returns Promise<
      {
          roots: {
              _meta?: { [key: string]: unknown };
              name?: string;
              uri: string;
          }[];
      },
  >
  Array of root objects with URI and optional name

Example

if (context.listRoots) {
  const { roots } = await context.listRoots();
  for (const root of roots) {
    console.log(`Root: ${root.uri} (${root.name})`);
  }
}

`Optional` `Readonly`reportProgress

reportProgress?: ProgressReporter

Reports progress for long-running operations.

MCP Protocol: Sends notifications/progress to the client.

Only available if the MCP client requested progress tracking by including _meta.progressToken in the tools/call request. If not requested, this will be undefined.

The framework applies rate-limiting (100ms minimum interval) to prevent flooding the client with notifications.

Param: data

Progress data to report

Returns

true if notification was sent successfully, false if rate-limited

`Readonly`requestId

requestId: string | number

The JSON-RPC request ID for this tool call.

Useful for logging, tracing, and correlating requests. This is the real protocol-level request ID from the MCP client.

`Optional` `Readonly`sessionId

sessionId?: string

The session ID from the transport, if available.

Identifies which MCP client session invoked this tool. Available in HTTP transport mode (Streamable HTTP, SSE), not in stdio.

`Readonly`stateless

stateless: boolean

Whether this tool is executing in stateless mode.

In stateless mode, the server creates a fresh session per request — no persistent state is maintained between calls.

Per-request features (work normally in stateless):

Progress reporting via SSE events in the POST response stream
AbortSignal (client closes connection → transport detects)
Logging notifications in the response stream

Cross-request features (unavailable in stateless by design):

Protocol cancellation (notifications/cancelled) — needs routing to original session
Sampling (sampling/createMessage) — server→client requires persistent channel
Elicitation (elicitation/create) — server→client requires persistent channel
Roots (roots/list) — server→client requires persistent channel
GET SSE streams and DELETE — no session ID for association

Tools MAY use this flag to adapt behavior for cross-request limitations, e.g., avoiding operations that rely on server-initiated client requests.

See

DD-019 for the design rationale behind these limitations

Interface ToolContext

Example

Hierarchy (View Summary)

Index

Properties

Properties

`Readonly`abortSignal

Example

`Optional` `Readonly`auth

Type Declaration

`Readonly`authInfo: AuthInfo

`Optional` `Readonly`extra?: Record<string, unknown>

Example

`Optional` `Readonly`createMessage

Type Declaration

Parameters

Example

`Optional` `Readonly`elicitInput

Type Declaration

Parameters

Example

`Optional` `Readonly`listRoots

Type Declaration

Returns Promise<
    {
        roots: {
            _meta?: { [key: string]: unknown };
            name?: string;
            uri: string;
        }[];
    },
>

Example

`Optional` `Readonly`reportProgress

Param: data

Returns

`Readonly`requestId

`Optional` `Readonly`sessionId

`Readonly`stateless

See

Settings

On This Page

Interface ToolContext

Example

Hierarchy (View Summary)

Index

Properties

Properties

ReadonlyabortSignal

Example

Optional Readonlyauth

Type Declaration

ReadonlyauthInfo: AuthInfo

Optional Readonlyextra?: Record<string, unknown>

Example

Optional ReadonlycreateMessage

Type Declaration

Parameters

Example

Optional ReadonlyelicitInput

Type Declaration

Parameters

Example

Optional ReadonlylistRoots

Type Declaration

Returns Promise< { roots: { _meta?: { [key: string]: unknown }; name?: string; uri: string; }[]; },>

Example

Optional ReadonlyreportProgress

Param: data

Returns

ReadonlyrequestId

Optional ReadonlysessionId

Readonlystateless

See

Settings

On This Page

`Readonly`abortSignal

`Optional` `Readonly`auth

`Readonly`authInfo: AuthInfo

`Optional` `Readonly`extra?: Record<string, unknown>

`Optional` `Readonly`createMessage

`Optional` `Readonly`elicitInput

`Optional` `Readonly`listRoots

Returns Promise<
{
roots: {
_meta?: { [key: string]: unknown };
name?: string;
uri: string;
}[];
},
>

`Optional` `Readonly`reportProgress

`Readonly`requestId

`Optional` `Readonly`sessionId

`Readonly`stateless