@adcp/sdk API Reference - v7.9.0
    Preparing search index...

    Interface AdcpCustomToolConfig<InputArgs, OutputArgs>

    Declarative registration for a tool outside AdcpToolMap — seller extensions (e.g. collection-list helpers), test-harness endpoints (comply_test_controller), or AdCP surfaces whose JSON Schemas haven't landed in the framework yet.

    These tools bypass the framework's spec-tool pipeline: idempotency middleware, governance pre-checks, account resolution, and response wrapping are all skipped. The handler receives the SDK-validated arguments and must return a CallToolResult directly. If you need any of those behaviors, call the framework helpers from inside the handler (e.g., checkGovernance(...), adcpError(...)).

    Type parameters match the SDK's McpServer.registerTool signature so argument and response types infer from the declared schemas.

    interface AdcpCustomToolConfig<
        InputArgs extends undefined
        | ZodRawShapeCompat
        | AnySchema = undefined,
        OutputArgs extends ZodRawShapeCompat | AnySchema | undefined = undefined,
    > {
        description?: string;
        title?: string;
        inputSchema?: InputArgs;
        outputSchema?: OutputArgs;
        annotations?: {
            title?: string;
            readOnlyHint?: boolean;
            destructiveHint?: boolean;
            idempotentHint?: boolean;
            openWorldHint?: boolean;
        };
        handler: BaseToolCallback<
            {
                _meta?: {
                    progressToken?: string
                    | number;
                    "io.modelcontextprotocol/related-task"?: { taskId: string };
                    [key: string]: unknown;
                };
                content: (
                    | {
                        type: "text";
                        text: string;
                        annotations?: {
                            audience?: ("user" | "assistant")[];
                            priority?: number;
                            lastModified?: string;
                        };
                        _meta?: { [key: string]: unknown };
                    }
                    | {
                        type: "image";
                        data: string;
                        mimeType: string;
                        annotations?: {
                            audience?: ("user" | "assistant")[];
                            priority?: number;
                            lastModified?: string;
                        };
                        _meta?: { [key: string]: unknown };
                    }
                    | {
                        type: "audio";
                        data: string;
                        mimeType: string;
                        annotations?: {
                            audience?: ("user" | "assistant")[];
                            priority?: number;
                            lastModified?: string;
                        };
                        _meta?: { [key: string]: unknown };
                    }
                    | {
                        uri: string;
                        description?: string;
                        mimeType?: string;
                        size?: number;
                        annotations?: {
                            audience?: ("user" | "assistant")[];
                            priority?: number;
                            lastModified?: string;
                        };
                        _meta?: { [key: string]: unknown };
                        icons?: {
                            src: string;
                            mimeType?: string;
                            sizes?: string[];
                            theme?: "light" | "dark";
                        }[];
                        name: string;
                        title?: string;
                        type: "resource_link";
                    }
                    | {
                        type: "resource";
                        resource: | {
                            uri: string;
                            mimeType?: string;
                            _meta?: { [key: string]: unknown };
                            text: string;
                        }
                        | {
                            uri: string;
                            mimeType?: string;
                            _meta?: { [key: string]: unknown };
                            blob: string;
                        };
                        annotations?: {
                            audience?: ("user" | "assistant")[];
                            priority?: number;
                            lastModified?: string;
                        };
                        _meta?: { [key: string]: unknown };
                    }
                )[];
                structuredContent?: { [key: string]: unknown };
                isError?: boolean;
                [key: string]: unknown;
            },
        >;
    }

    Type Parameters

    • InputArgs extends undefined | ZodRawShapeCompat | AnySchema = undefined
    • OutputArgs extends ZodRawShapeCompat | AnySchema | undefined = undefined
    Index

    Properties

    description? title? inputSchema? outputSchema? annotations? handler

    Properties

    description?: string

    Human-readable description — surfaced in tools/list.

    title?: string

    Optional title hint for the MCP inspector.

    inputSchema?: InputArgs

    Zod raw shape or schema for argument validation.

    outputSchema?: OutputArgs

    Zod raw shape or schema for the declared response payload.

    Forwarded verbatim to registerTool. The MCP SDK validates every non-error response's structuredContent against this schema on the server AND on the buyer's client (the latter fires regardless of isError — see the NOTE on outputSchema block earlier in this file). Framework-registered AdCP tools skip this field for that reason; custom tools opt in here and own the trade-off.

    Footgun: a too-strict schema (e.g. z.never(), or one that accidentally rejects the caller's own valid shape) turns the tool into a silent client-side validation error for every buyer. The seller sees a successful response go out; the buyer receives an Output validation error. Test against a real buyer call before relying on this.

    annotations?: {
        title?: string;
        readOnlyHint?: boolean;
        destructiveHint?: boolean;
        idempotentHint?: boolean;
        openWorldHint?: boolean;
    }

    Tool annotations (readOnlyHint / destructiveHint / idempotentHint / openWorldHint).

    handler: BaseToolCallback<
        {
            _meta?: {
                progressToken?: string
                | number;
                "io.modelcontextprotocol/related-task"?: { taskId: string };
                [key: string]: unknown;
            };
            content: (
                | {
                    type: "text";
                    text: string;
                    annotations?: {
                        audience?: ("user" | "assistant")[];
                        priority?: number;
                        lastModified?: string;
                    };
                    _meta?: { [key: string]: unknown };
                }
                | {
                    type: "image";
                    data: string;
                    mimeType: string;
                    annotations?: {
                        audience?: ("user" | "assistant")[];
                        priority?: number;
                        lastModified?: string;
                    };
                    _meta?: { [key: string]: unknown };
                }
                | {
                    type: "audio";
                    data: string;
                    mimeType: string;
                    annotations?: {
                        audience?: ("user" | "assistant")[];
                        priority?: number;
                        lastModified?: string;
                    };
                    _meta?: { [key: string]: unknown };
                }
                | {
                    uri: string;
                    description?: string;
                    mimeType?: string;
                    size?: number;
                    annotations?: {
                        audience?: ("user" | "assistant")[];
                        priority?: number;
                        lastModified?: string;
                    };
                    _meta?: { [key: string]: unknown };
                    icons?: {
                        src: string;
                        mimeType?: string;
                        sizes?: string[];
                        theme?: "light" | "dark";
                    }[];
                    name: string;
                    title?: string;
                    type: "resource_link";
                }
                | {
                    type: "resource";
                    resource: | {
                        uri: string;
                        mimeType?: string;
                        _meta?: { [key: string]: unknown };
                        text: string;
                    }
                    | {
                        uri: string;
                        mimeType?: string;
                        _meta?: { [key: string]: unknown };
                        blob: string;
                    };
                    annotations?: {
                        audience?: ("user" | "assistant")[];
                        priority?: number;
                        lastModified?: string;
                    };
                    _meta?: { [key: string]: unknown };
                }
            )[];
            structuredContent?: { [key: string]: unknown };
            isError?: boolean;
            [key: string]: unknown;
        },
    >

    Tool handler. Gets SDK-validated args based on inputSchema and must return a CallToolResult. Use capabilitiesResponse, mediaBuyResponse, adcpError, or a hand-built { content, structuredContent? }.

    Settings

    Member Visibility

    On This Page

    Properties