Introduction

Toolgrain is a TypeScript toolkit for building Model Context Protocol servers. Define tools with Zod, compose them into a server, and connect them to your application’s services over stdio or HTTP.

Build your first server

Install Toolgrain, define a tool, and make your first MCP call.

Explore the examples

Start from stdio, Node HTTP, Express, Hono, Elysia, or Next.js.

Define a tool once

Describe the input and output with Zod. Toolgrain infers your handler’s types and validates values at runtime.

import { tool } from "@toolgrain/mcp";
import { z } from "zod";

const greet = tool({
  description: "Greet someone by name",
  input: z.object({ name: z.string().min(1) }),
  output: z.object({ message: z.string() }),
  execute: ({ name }) => ({ message: `Hello, ${name}!` }),
});

Register greet with createServer({ name, version, tools: { greet } }). The registration key becomes the name clients discover and call. Reuse the same tool definition across servers and transports.

Build around your application

Types follow your schemas. Input and declared output schemas check handler types and parse runtime values, including defaults and transforms.
Tools compose. Keep definitions alongside the application services they expose, then choose which tools each server registers.
Choose your transport. Use stdio, start a Node HTTP listener, or mount a Web or Node handler in an existing application.
Add dependencies and authorization. Resolve services through typed, lazy context providers and protect HTTP endpoints with JWT or Clerk OAuth.

Toolgrain implements MCP directly, independently of @modelcontextprotocol/sdk.

Choose your packages

Start with @toolgrain/mcp and a transport package. Install the same version across Toolgrain libraries.

Package	What it provides
`@toolgrain/mcp`	Tool definitions, servers, validation, rich results, and request context
`@toolgrain/node`	Stdio, a managed HTTP listener, and Node HTTP handlers
`@toolgrain/http`	Web `Request`/`Response` handlers for existing applications
`@toolgrain/jwt`	JWT access-token verification for HTTP endpoints
`@toolgrain/clerk`	Clerk OAuth access-token verification for HTTP endpoints
`@toolgrain/protocol`	Pinned MCP wire types and protocol version constants

Compatibility and scope

Requirement	Supported
Module format	ESM
Node.js	`^24.20.0`
Bun applications	`>=1.4.4 <2`
TypeScript	5.5.4 or later, with strict mode
Zod	`^4.6.6`, Classic or Mini
MCP revisions	`2026-07-28` and `2025-06-18`

Both MCP revisions use the same tool API over stdio and HTTP. HTTP uses independent POST requests with JSON responses. Sessions, SSE, resumability, resources, prompts, elicitation, progress, and subscriptions are outside the current implementation. See the support policy for runtime and dependency commitments, and client compatibility for verified client versions and flows.

Go further

Tool authoring

Define schemas, return rich content, and use request context and cancellation.

Context providers

Connect tools to databases and services with request-scoped caching.

HTTP and frameworks

Pick a listener or handler that fits your application.

Authorization

Verify access tokens and read verified identities in your tools.

Getting started

Writing tools

Context and services

Transports

Authorization

Testing and operations

Compatibility

Build your first server

Explore the examples

Define a tool once

Build around your application

Choose your packages

Compatibility and scope

Go further

Tool authoring

Context providers

HTTP and frameworks

Authorization

Build your first server

Explore the examples

​Define a tool once

​Build around your application

​Choose your packages

​Compatibility and scope

​Go further

Tool authoring

Context providers

HTTP and frameworks

Authorization

Define a tool once

Build around your application

Choose your packages

Compatibility and scope

Go further