webmcp-add-tool

Add a WebMCP Tool

Overview

Each tool is a React component that calls useMcpTool. It registers on mount, unregisters on unmount. Tools can be headless (return null) or render UI showing execution state.

Workflow

1. Determine the tool's name, description, input schema, and what the handler does
2. Choose headless vs UI tool
3. Scaffold using the appropriate template below
4. Set annotations based on tool behavior
5. Wire the component into the <WebMCPProvider> tree

Template: Headless tool

For tools that do work without rendering anything visible:

import { useMcpTool } from "webmcp-react";
import { z } from "zod";

export function MyTool() {
  useMcpTool({
    name: "my_tool",
    description: "One-line description of what this tool does",
    input: z.object({
      // Define each input field with .describe() for AI context
      query: z.string().describe("The search query"),
    }),
    handler: async ({ query }, { signal }) => {
      // signal aborts if the agent cancels — forward it to cancellable work
      const result = await doSomething(query, { signal });
      return {
        content: [{ type: "text", text: JSON.stringify(result) }],
      };
    },
  });
  return null;
}

Template: Tool with execution state UI

For tools that show loading, results, or errors:

import { useMcpTool } from "webmcp-react";
import { z } from "zod";

export function MyTool() {
  const { state, execute, reset } = useMcpTool({
    name: "my_tool",
    description: "One-line description of what this tool does",
    input: z.object({
      text: z.string().describe("Input text to process"),
    }),
    handler: async ({ text }) => {
      const result = await process(text);
      return { content: [{ type: "text", text: result }] };
    },
    onSuccess: (result) => {
      // Optional: analytics, toast, etc.
    },
    onError: (error) => {
      // Optional: error reporting
    },
  });

  return (
    <div>
      <button onClick={() => execute({ text: "hello" })} disabled={state.isExecuting}>
        {state.isExecuting ? "Processing..." : "Run"}
      </button>
      {state.lastResult && <p>{state.lastResult.content[0].text}</p>}
      {state.error && <p className="error">{state.error.message}</p>}
      <span>Executions: {state.executionCount}</span>
    </div>
  );
}