OpenAI

Tools are functions that your LLM can actively call and decides when to use based on user requests. They enable AI models to perform actions such as writing to databases, calling external APIs, modifying files, or triggering other logic.

By default, xmcp detects files under the /src/tools/ directory and registers them as tools, but you can specify a custom directory if you prefer. The directory to use can be configured in the xmcp.config.ts file.

A tool file consists of three main exports:

Default: The tool handler function.
Schema (optional): The input parameters using Zod schemas.
Metadata (optional): The tool's identity and behavior hints. If omitted, the name is inferred from the file name and the description defaults to a placeholder.

src/tools/greet.ts

import { z } from "zod";
import { type InferSchema } from "xmcp";

// Define the schema for tool parameters
export const schema = {
  name: z.string().describe("The name of the user to greet"),
};

// Define tool metadata
export const metadata = {
  name: "greet",
  description: "Greet the user",
  annotations: {
    title: "Greet the user",
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
  },
};

// Tool implementation
export default async function greet({ name }: InferSchema<typeof schema>) {
  const result = `Hello, ${name}!`;

  return {
    content: [{ type: "text", text: result }],
  };
}

If you're returning a string or number only, you can shortcut the return value to be the string or number directly.

export default async function greet({ name }: InferSchema<typeof schema>) {
  return `Hello, ${name}!`;
}

We encourage to use this shortcut for readability, and restrict the usage of the content array type only for complex responses, like images, audio or videos.

Schema Definition

The schema defines your tool's input parameters using Zod. Use .describe() on each parameter to help LLMs understand how to use your tool correctly.

src/tools/create-user.ts

import { z } from "zod";
import { type InferSchema } from "xmcp";

export const schema = {
  name: z.string().describe("User's full name"),
  email: z.string().email().describe("Valid email address"),
  age: z.number().min(18).optional().describe("User's age (18+)"),
  role: z.enum(["admin", "user"]).describe("User role"),
};

export default async function createUser(args: InferSchema<typeof schema>) {
  // args is automatically typed: { name: string; email: string; age?: number; role: "admin" | "user" }
  const { name, email, age, role } = args;
  // Implementation here
}

Type Inference

The InferSchema utility automatically infers TypeScript types from your Zod schema, giving you full type safety without manual type definitions:

import { type InferSchema } from "xmcp";

export const schema = {
  tags: z.array(z.string()).describe("List of tags"),
  metadata: z
    .object({
      priority: z.number(),
      assignee: z.string().optional(),
    })
    .describe("Task metadata"),
};

// TypeScript infers:
// {
//   tags: string[];
//   metadata: { priority: number; assignee?: string };
// }
export default async function handler(args: InferSchema<typeof schema>) {
  // Full autocomplete and type checking
  args.tags.forEach((tag) => console.log(tag));
  args.metadata.priority; // number
  args.metadata.assignee; // string | undefined
}

Clear descriptions are crucial for LLM tool discovery. For comprehensive Zod validation options (regex patterns, constraints, transformations), see the Zod documentation.

Metadata

The metadata export defines your tool's identity and provides behavioral hints to LLMs and clients.

src/tools/delete-user.ts

import { type ToolMetadata } from "xmcp";

export const metadata: ToolMetadata = {
  name: "delete-user",
  description: "Permanently delete a user account",
  annotations: {
    title: "Delete User Account",
    destructiveHint: true,
    idempotentHint: false,
  },
};

Core Properties

name (required)

Unique identifier for the tool
Defaults to the filename if not provided
Use kebab-case (e.g., get-user-profile)

description (required)

Clear explanation of what the tool does
Defaults to placeholder if not provided
Critical for LLM tool discovery and selection

Annotations

Behavioral hints that help LLMs and UIs understand how to use your tool:

annotations: {
  // Human-readable title displayed in UIs
  title: "Create New Task",

  // Tool doesn't modify its environment (safe to retry)
  readOnlyHint: true,

  // Tool may perform destructive updates (use with caution)
  destructiveHint: false,

  // Repeated calls with same args have no additional effect
  idempotentHint: true,

  // Tool interacts with external entities (APIs, databases)
  openWorldHint: true,
}

These hints are advisory only. LLMs may use them to make better decisions about when and how to call your tools, but they don't enforce any behavior.

OpenAI Metadata

For ChatGPT widget integration, add OpenAI-specific metadata under _meta.openai:

export const metadata: ToolMetadata = {
  name: "show-analytics",
  description: "Display analytics dashboard",
  _meta: {
    openai: {
      // Tool-specific
      widgetAccessible: true,
      toolInvocation: {
        invoking: "Loading analytics...",
        invoked: "Dashboard ready!",
      },

      // Resource-specific (for auto-generated widgets)
      widgetDescription: "Real-time analytics dashboard",
      widgetPrefersBorder: true,
      widgetCSP: {
        connect_domains: ["https://api.analytics.com"],
        resource_domains: ["https://cdn.analytics.com"],
      },
    },
  },
};

Tool-specific properties:

widgetAccessible - Enable widget-to-tool communication (required for widgets)
toolInvocation.invoking - Message shown while executing (≤64 chars)
toolInvocation.invoked - Message shown after completion (≤64 chars)
outputTemplate - Custom widget URI (auto-generated if not provided)

Resource-specific properties:

widgetDescription - Human-readable widget summary
widgetPrefersBorder - UI rendering hint for borders
widgetCSP - Content Security Policy for external resources
widgetDomain - Optional dedicated subdomain
widgetState - Initial state object passed to widget

Handler Types

Tools support three types of handlers, each suited for different use cases:

Type	Best For	Returns
Standard	Data queries, calculations, API calls	Unstructured or structured content
Template Literal	Simple widgets with external scripts	HTML string
React Component	Interactive, stateful widgets	React component

1. Standard Handlers

Standard handlers are functions that return text, structured content, or simple data. This is the default approach for most tools.

When to use:

Performing calculations or data transformations
Calling external APIs and returning results
Querying databases
Any task that returns text or structured data without UI interaction

src/tools/calculate.ts

import { z } from "zod";
import { type InferSchema } from "xmcp";

export const schema = {
  operation: z.enum(["add", "subtract"]),
  a: z.number(),
  b: z.number(),
};

export const metadata = {
  name: "calculate",
  description: "Perform basic calculations",
};

export default async function calculate({
  operation,
  a,
  b,
}: InferSchema<typeof schema>) {
  const result = operation === "add" ? a + b : a - b;
  return `Result: ${result}`;
}

2. Template Literal Handlers

Return HTML directly to create interactive widgets in ChatGPT. When you return HTML and include OpenAI metadata, xmcp automatically generates a widget resource.

To enable widgets, you need to add the _meta.openai configuration in your metadata with widgetAccessible: true.

src/tools/show-chart.ts

import { type ToolMetadata } from "xmcp";

export const metadata: ToolMetadata = {
  name: "show-chart",
  description: "Display an interactive chart",
  _meta: {
    openai: {
      widgetAccessible: true,
      toolInvocation: {
        invoking: "Loading chart...",
        invoked: "Chart loaded!",
      },
    },
  },
};

export default async function showChart() {
  return `
    <div id="chart-container">
      <h2>Sales Data</h2>
      <canvas id="chart"></canvas>
    </div>
    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
    <script>
      // Chart initialization code
    </script>
  `;
}

3. React Component Handlers

Return React components for interactive, composable widgets. xmcp renders the component to HTML and generates a widget resource automatically.

To enable widgets, you need to add the _meta.openai configuration in your metadata with widgetAccessible: true.

src/tools/interactive-todo.tsx

import { type ToolMetadata } from "xmcp";
import { useState } from "react";

export const metadata: ToolMetadata = {
  name: "interactive-todo",
  description: "Interactive todo list widget",
  _meta: {
    openai: {
      widgetAccessible: true,
      toolInvocation: {
        invoking: "Loading todo list...",
        invoked: "Todo list ready!",
      },
    },
  },
};

export default function InteractiveTodo() {
  const [todos, setTodos] = useState<string[]>([]);
  const [input, setInput] = useState("");

  const addTodo = () => {
    if (input.trim()) {
      setTodos([...todos, input]);
      setInput("");
    }
  };

  return (
    <div>
      <h2>Todo List</h2>
      <input
        type="text"
        value={input}
        onChange={(e) => setInput(e.target.value)}
        placeholder="Add a todo..."
      />
      <button onClick={addTodo}>Add</button>
      <ul>
        {todos.map((todo, idx) => (
          <li key={idx}>{todo}</li>
        ))}
      </ul>
    </div>
  );
}

Setup Requirements:

Use .tsx file extension for React component tools
Install React dependencies: npm install react react-dom
Configure tsconfig.json:

{
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}

Return Values

Tools support multiple return formats depending on your needs:

Simple Values

Return strings or numbers directly - xmcp automatically wraps them in the proper format:

export default async function calculate() {
  return "Result: 42"; // or return 42;
}

Content Array

Return an object with a content array for rich media responses:

export default async function getProfile() {
  return {
    content: [
      {
        type: "text",
        text: "Profile information:",
      },
      {
        type: "image",
        data: "base64encodeddata",
        mimeType: "image/jpeg",
      },
      {
        type: "resource_link",
        name: "Full Profile",
        uri: "resource://profile/john",
      },
    ],
  };
}

Supported content types:

text - Plain text content
image - Base64-encoded images with mimeType
audio - Base64-encoded audio with mimeType
resource_link - Links to MCP resources

Structured Outputs

Return structured data using the structuredContent property:

export default async function getUserData() {
  return {
    structuredContent: {
      user: {
        id: 123,
        name: "John Doe",
        email: "john@example.com",
      },
      metadata: {
        timestamp: new Date().toISOString(),
      },
    },
  };
}

Combined Response

Return both content and structuredContent for backwards compatibility. If the client cannot process structured outputs, it will fallback to content.

export default async function getData() {
  return {
    content: [
      {
        type: "text",
        text: "Data retrieved successfully",
      },
    ],
    structuredContent: {
      data: { key: "value" },
    },
  };
}

Tools

One framework to rule them all