mcp-builder

Define a tool with server.tool() by passing a name, description, and Zod schema, plus an async callback that returns a response helper like text() or object(). Add .describe() to every schema field and use the error() helper inside try/catch for failures.

Create a React component in the resources folder exporting widgetMetadata with a props Zod schema and a default component, then reference it in the tool's widget config by name. Return widget() from the tool callback with props for the UI and output text for the model.

Use a widget when browsing multiple items, displaying visual data like charts or colors, or enabling interactive selection. Use plain text tools for simple outputs like translations, calculations, or status checks where no visual element adds value.

Widgets render before the tool finishes executing, so props are initially empty. Check the isPending flag from useWidget() first and render a loading state until it becomes false, then access props safely.

Yes, server.proxy() composes multiple local or remote MCP servers into a single aggregator server with namespaced tools. It handles schema translation, progress notifications, and state synchronization automatically.

The error occurs when widgetMetadata sets exposeAsTool to true while a custom tool also references the widget. Remove exposeAsTool since it defaults to false and the custom tool definition handles registration.