How to Create Custom MCP Tools: Developer Guide

A custom MCP tool has three parts: a name, an input schema, and a handler. Getting the schema right matters most — it's what the model uses to decide when and how to call your tool.

Defining the Schema

server.setRequestHandler("tools/list", () => ({
  tools: [{
    name: "search_orders",
    description: "Search orders by customer email or order ID",
    inputSchema: {
      type: "object",
      properties: {
        query: { type: "string", description: "Email or order ID" },
        limit: { type: "number", default: 10 }
      },
      required: ["query"]
    }
  }]
}));

Writing the Handler

Keep handlers pure and idempotent where possible. Validate arguments before touching external systems, and return a concise, structured result — the model re-reads whatever you return, so verbosity costs context.

Share Your Tool

Post your tool definitions in the showcase gallery below — reviewers often catch schema ambiguities you won't notice until a model misuses them.