Why Toolgrain keeps MCP tools separate from servers

Toolgrain is a toolkit designed to separate tool definitions from server execution and transport mechanisms. This separation allows for greater flexibility and reuse of tool definitions across different MCP servers. The core idea is to define a tool as a standalone, self-contained entity that includes its description, Zod schemas, and handler function.

A server registers these tool definitions under specific names, which are then discoverable by MCP clients. The transport layer is responsible for handling how requests are received, such as through stdio or HTTP POST requests.

For example, a TypeScript tool can be defined in a file like `server.mts`, where the tool's schema and behavior are specified using Zod for input validation and output structuring. The server is then created using the `createServer` function, specifying the tool names and their corresponding handler functions. The server can be started, listening for requests on stdin/stdout using a transport such as `stdio()`.

When a tool is invoked via the MCP Inspector CLI, the tool's TypeScript definition is separate from the actual server implementation. The server acts merely as a mediator, validating the input against the tool's schema and returning the result according to the specified output schema. This separation enables the same tool to be used across multiple servers, each potentially using a different transport mechanism or server-side implementation.

By keeping tool definitions, server execution, and transport mechanisms separate, Toolgrain provides a modular and flexible approach to building MCP-based applications. This design enables developers to define reusable tool logic, register them under desired names, and manage how they are accessed and executed across various environments.