MCP Server Framework - v1.1.2
    Preparing search index...

    Interface ToolDefinition<TInput, TOutput>

    Tool definition - the canonical type for MCP tools.

    This is the ONLY type needed for defining and registering tools. Used by defineTool(), ToolRegistry, and McpServerBuilder.

    const greetTool = defineTool({
      name: 'greet',
      description: 'Greet a user by name',
      input: z.object({ name: z.string() }),
      handler: async ({ name }, ctx) => text(`Hello, ${name}!`),
    });
    interface ToolDefinition<
        TInput extends ZodTypeAny = ZodTypeAny,
        TOutput extends ZodTypeAny = ZodTypeAny,
    > {
        _meta?: Record<string, unknown>;
        annotations?: ToolAnnotations;
        description: string;
        handler: (
            args: TypeOf<TInput>,
            context: ToolContext,
        ) => 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";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        description?: string;
                        icons?: {
                            mimeType?: string;
                            sizes?: (...)[];
                            src: string;
                            theme?: "light" | "dark";
                        }[];
                        mimeType?: string;
                        name: string;
                        size?: number;
                        title?: string;
                        type: "resource_link";
                        uri: string;
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        resource: | {
                            _meta?: { [key: string]: unknown };
                            mimeType?: string;
                            text: string;
                            uri: string;
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            blob: string;
                            mimeType?: string;
                            uri: string;
                        };
                        type: "resource";
                    }
                )[];
                isError?: boolean;
                structuredContent?: { [key: string]: unknown };
                [key: string]: unknown;
            },
        >;
        input: TInput;
        name: string;
        output?: TOutput;
        requiredScopes?: readonly string[];
    }

    Type Parameters

    Index

    Properties

    _meta? annotations? description handler input name output? requiredScopes?

    Properties

    Optional Readonly_meta

    _meta?: Record<string, unknown>

    Optional metadata passed through to the MCP SDK tool registration.

    This is a generic passthrough for protocol-level metadata like { ui: { resourceUri: 'app://my-app' } } used by MCP Apps. The framework does not interpret _meta — it is forwarded as-is.

    annotations?: ToolAnnotations

    Optional annotations providing hints about tool behavior.

    Per MCP specification, annotations help clients understand tool characteristics without needing to parse the description. These are hints, not guarantees.

    https://modelcontextprotocol.io/specification/2025-03-26/server/tools#annotations

    description: string

    Human-readable description shown to LLM

    handler: (
        args: TypeOf<TInput>,
        context: ToolContext,
    ) => 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";
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    description?: string;
                    icons?: {
                        mimeType?: string;
                        sizes?: (...)[];
                        src: string;
                        theme?: "light" | "dark";
                    }[];
                    mimeType?: string;
                    name: string;
                    size?: number;
                    title?: string;
                    type: "resource_link";
                    uri: string;
                }
                | {
                    _meta?: { [key: string]: unknown };
                    annotations?: {
                        audience?: ((...) | (...))[];
                        lastModified?: string;
                        priority?: number;
                    };
                    resource: | {
                        _meta?: { [key: string]: unknown };
                        mimeType?: string;
                        text: string;
                        uri: string;
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        blob: string;
                        mimeType?: string;
                        uri: string;
                    };
                    type: "resource";
                }
            )[];
            isError?: boolean;
            structuredContent?: { [key: string]: unknown };
            [key: string]: unknown;
        },
    >

    Tool handler function.

    Type Declaration

      • (
            args: TypeOf<TInput>,
            context: ToolContext,
        ): 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";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        description?: string;
                        icons?: {
                            mimeType?: string;
                            sizes?: (...)[];
                            src: string;
                            theme?: "light" | "dark";
                        }[];
                        mimeType?: string;
                        name: string;
                        size?: number;
                        title?: string;
                        type: "resource_link";
                        uri: string;
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        resource: | {
                            _meta?: { [key: string]: unknown };
                            mimeType?: string;
                            text: string;
                            uri: string;
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            blob: string;
                            mimeType?: string;
                            uri: string;
                        };
                        type: "resource";
                    }
                )[];
                isError?: boolean;
                structuredContent?: { [key: string]: unknown };
                [key: string]: unknown;
            },
        >

      • Parameters

        • args: TypeOf<TInput>

          Validated input (typed from Zod schema)

        • context: ToolContext

          Execution context with progress reporter, abort signal

        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";
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        description?: string;
                        icons?: {
                            mimeType?: string;
                            sizes?: (...)[];
                            src: string;
                            theme?: "light" | "dark";
                        }[];
                        mimeType?: string;
                        name: string;
                        size?: number;
                        title?: string;
                        type: "resource_link";
                        uri: string;
                    }
                    | {
                        _meta?: { [key: string]: unknown };
                        annotations?: {
                            audience?: ((...) | (...))[];
                            lastModified?: string;
                            priority?: number;
                        };
                        resource: | {
                            _meta?: { [key: string]: unknown };
                            mimeType?: string;
                            text: string;
                            uri: string;
                        }
                        | {
                            _meta?: { [key: string]: unknown };
                            blob: string;
                            mimeType?: string;
                            uri: string;
                        };
                        type: "resource";
                    }
                )[];
                isError?: boolean;
                structuredContent?: { [key: string]: unknown };
                [key: string]: unknown;
            },
        >

        MCP CallToolResult (use response helpers: text(), json(), error())

    input: TInput

    Zod schema for input validation

    name: string

    Unique tool name (e.g., 'greet', 'list_servers')

    output?: TOutput

    Optional Zod schema for the tool's structured output.

    When set, the framework forwards the schema to the MCP SDK as outputSchema. Clients can then read the schema from tools/list and the SDK validates that the handler returns structuredContent matching this shape on every call.

    https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content

    requiredScopes?: readonly string[]

    Scopes required to execute this tool (RBAC).

    When set, the framework checks authInfo.scopes BEFORE the handler executes. All listed scopes must be present (AND logic). If the check fails, a 403 Forbidden error is returned.

    Omit or set to undefined for tools accessible to any authenticated user.

    Settings

    Member Visibility

    On This Page

    Properties