JSON to MCP Tool: Build Type-Safe AI Agent Tools Instantly

JSON to MCP Tool: Generate Model Context Protocol Tool Definitions from JSON

The Model Context Protocol (MCP) lets you expose tools to AI agents like Claude, Cursor, and Windsurf. Every MCP tool needs a Zod schema describing its parameters — writing these by hand for every tool is error-prone and repetitive. TypeMorph infers the schema from a real JSON payload and generates a ready-to-run MCP tool definition in seconds.

Live Example: From JSON to MCP Tool

// Input JSON (a sample API request payload)
{
  "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "[email protected]",
  "action": "send_report",
  "count": 5
}

// Generated MCP Tool
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

server.tool(
  "root",
  "Auto-generated MCP tool — replace with a meaningful description",
  {
    user_id: z.uuid().describe("UUID identifier for the user"),
    email: z.email().describe("Email address"),
    action: z.string().describe("Action to perform"),
    count: z.number().int().min(0).describe("Count value"),
  },
  async ({ user_id, email, action, count }) => ({
    content: [{ type: "text", text: JSON.stringify({ user_id, email, action, count }) }]
  })
);

export { server };

Step-by-Step Setup

1. Install the MCP SDK: npm install @modelcontextprotocol/sdk zod
2. Paste your JSON payload into TypeMorph and select MCP Tool as the output format.
3. Update the tool name and description — replace "root" with a verb-noun name like "createUser" and write a description that tells the AI agent what the tool does.
4. Add your implementation inside the async handler — replace the JSON.stringify echo with your actual business logic.
5. Connect your server to a transport (stdio for local tools, SSE for remote).

Technical Deep Dive: Why Zod for MCP Parameters

MCP uses Zod schemas to validate tool inputs before passing them to your handler, and to generate JSON Schema for the AI agent's function-calling interface. TypeMorph's semantic inference means field names like email automatically get z.email(), UUIDs get z.uuid(), and numeric fields get appropriate .min()/.max() constraints. This gives the AI agent better hints about what values are valid, reducing hallucinated or invalid inputs.

MCP Tool Naming Best Practices

AI agents read the tool name and description to decide when to call your tool. Use verb-noun names like getUserById, sendInvoice, or queryDatabase. Avoid generic names like process or run. The description should explain what the tool does and when to use it — one or two sentences is ideal. Each parameter's .describe() string is shown to the agent, so describe the expected format and units (e.g., "Unix timestamp in seconds" or "ISO 4217 currency code like USD").

Connecting to Claude Desktop / Cursor

For a stdio transport (the most common for local tools), add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "my-tool": {
      "command": "node",
      "args": ["/path/to/your/server.js"]
    }
  }
}

For Cursor, add the same configuration to .cursor/mcp.json in your project root.

Best Practices

• One tool per operation: Avoid tools with 20+ parameters. Split complex operations into focused tools — agents perform better with smaller, well-named tools.
• Use .describe() on every parameter: The agent uses these strings to understand what to pass. Skip them and the agent guesses.
• Return structured JSON: Wrap your response in JSON.stringify() so downstream tools can parse the output programmatically.
• Add error handling: Return { content: [{ type: "text", text: errorMessage }], isError: true } for recoverable errors so the agent can retry or escalate.

FAQ

Q: Can I use this with FastMCP or other MCP frameworks?
A: Yes. FastMCP uses the same Zod schema format for tool parameters. Copy the parameter object from the generated output and use it directly in your FastMCP server.addTool() call.

Q: Does TypeMorph support Standard Schema instead of Zod?
A: The MCP Tool generator outputs Zod (v4) by default, which is the most widely used option. If your framework supports Standard Schema, the Zod output is compatible as Zod 4 implements the Standard Schema interface.

Q: How do I handle optional parameters in my MCP tool?
A: Fields that were null or absent in your JSON sample are generated as .optional(). MCP agents will omit optional parameters when they don't have a value, and your handler should handle undefined for those fields.