Build and deploy TypeScript-based MCP servers with Zod validation, supporting both stdio and HTTP transports.
Also known as keshavkatwe/toolgrain, @toolgrain/clerk, @toolgrain/http, @toolgrain/jwt, @toolgrain/mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 10, 2026
- License
- MIT
What is toolgrain MCP?
toolgrain builds and deploy TypeScript-based MCP servers with Zod validation, supporting both stdio and HTTP transports.
Summary generated from the project's README
About toolgrain MCP server
Developers building TypeScript applications can use Toolgrain to expose their services to Model Context Protocol clients through schema-validated tools. The toolkit allows you to define reusable tools using Zod, which automatically infers handler inputs and validates outputs at runtime. This ensures that the data flowing between your application and an AI client remains consistent with your defined schemas.
You can deploy these tools using either stdio or HTTP transports, making it easy to integrate with existing Node.js or Bun environments. For local development, you can use the MCP Inspector to test your server. If you prefer a remote setup, you can run a Node HTTP listener or mount handlers in web frameworks like Express, Hono, or Next.js. The toolkit also provides specialized packages for adding JWT or Clerk OAuth authorization to protect your HTTP endpoints.
What you can do with it
- 1Validate tool inputs and outputsUse Zod schemas to ensure that the data sent to and from your AI tools is correctly formatted.
- 2Deploy via multiple transportsYou can choose to run your server locally via stdio or host it remotely using an HTTP endpoint.
- 3Secure remote tool endpointsProtect your HTTP-based MCP tools using standard identity verification methods like JWT.
Written from the project's README. Every use case is checked against a quote from it.
How to install toolgrain MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall toolgrain MCP in Claude Code
$ claude mcp add toolgrain -- npx -y @toolgrain/clerkInstall toolgrain MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"toolgrain": {
"command": "npx",
"args": [
"-y",
"@toolgrain/clerk"
]
}
}
}Install toolgrain MCP in VS Code
.vscode/mcp.json
{
"servers": {
"toolgrain": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@toolgrain/clerk"
]
}
}
}Install toolgrain MCP in VS Code CLI
$ code --add-mcp '{"name":"toolgrain","type":"stdio","command":"npx","args":["-y","@toolgrain/clerk"]}'Install toolgrain MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"toolgrain": {
"command": "npx",
"args": [
"-y",
"@toolgrain/clerk"
]
}
}
}Install toolgrain MCP in Codex
$ codex mcp add toolgrain -- npx -y @toolgrain/clerkInstall toolgrain MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.toolgrain] command = "npx" args = ["-y", "@toolgrain/clerk"]
Install toolgrain MCP in Gemini CLI
$ gemini mcp add -s user toolgrain npx -- -y @toolgrain/clerkInstall toolgrain MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"toolgrain": {
"command": "npx",
"args": [
"-y",
"@toolgrain/clerk"
]
}
}
}Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablekeshavkatwe/toolgrain is public and reachablegithub.com/keshavkatwe/toolgrain ↗Pass
- Package names this repository as its source@toolgrain/clerk, @toolgrain/http name keshavkatwe/toolgrain as sourcenpmjs.com/package/@toolgrain/clerk ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @toolgrain/clerk, @toolgrain/httpnpmjs.com/package/@toolgrain/clerk/v/0.4.0#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/keshavkatwe/toolgrain ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @toolgrain/clerk, @toolgrain/http, @toolgrain/jwt, @toolgrain/mcp, @toolgrain/node, @toolgrain/protocolPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubExpose your application's services to Model Context Protocol clients through standalone, schema-validated tools. Reuse the definitions across servers and choose stdio or HTTP for each application.
Quickstart
1. Install
Use Node.js ^24.20.0 and a TypeScript project with strict mode enabled.
In a new project directory, initialize npm and install matching stable Toolgrain
packages from npm's latest tag:
npm init -y
npm install @toolgrain/mcp @toolgrain/node zod@^4.6.6
npm install --save-dev typescript @types/node@^24.10.0
2. Define your tool and server
Save as server.mts. The registration key greet is the name clients use to
discover and call the tool.
import { createServer, tool } from "@toolgrain/mcp";
import { stdio } from "@toolgrain/node";
import { z } from "zod";
const greet = tool({
description: "Greet someone by name",
annotations: { readOnlyHint: true },
input: z.object({ name: z.string().min(1) }),
output: z.object({ message: z.string() }),
execute: ({ name }) => ({ message: `Hello, ${name}!` }),
});
const server = createServer({
name: "hello-server",
version: "1.0.0",
tools: { greet },
});
await server.listen(stdio());
3. Compile
npx tsc server.mts --strict --module NodeNext --target ES2022 --types node
4. Call your tool
Use MCP Inspector's CLI to start the compiled server and call greet:
npx --yes @modelcontextprotocol/inspector@2.11.0 --cli \
--protocol-era modern --format json \
--method tools/call --tool-name greet --tool-args-json '{"name":"Ada"}' \
node server.mjs
Inspector launches the server, prints the response, and exits. The response's
result.structuredContent contains:
{ "message": "Hello, Ada!" }
The result also includes the same JSON as text in content. For regular use,
configure your MCP client to start node with the absolute path to server.mjs
as its argument. The server waits for MCP requests on stdin; keep application
logs on stderr. See client compatibility for verified
client versions and setup.
Prefer HTTP?
Replace the stdio import and the last line with:
import { http } from "@toolgrain/node";
await server.listen(http({ port: 3000 }));
Your endpoint is http://127.0.0.1:3000/mcp. Call server.close() during
application shutdown. See transports for existing
listeners, HTTP headers, production hosts, and cancellation, or start from a
framework example.
Why Toolgrain?
Toolgrain implements MCP directly, independently of @modelcontextprotocol/sdk.
The current scope includes tools, fixed resources, progress, and React MCP Apps across two protocol revisions;
see support and scope before choosing it for your project.
Build beyond hello
| You want to… | Start here |
|---|---|
| Reuse tools, validate outputs, or return rich content | Tool authoring |
| Access request details or cancel work | Handler context |
| Inject a database or service into tools | Context providers |
| Protect an HTTP endpoint with JWT or Clerk | Authorization |
| Connect Inspector or check tested clients | Compatibility |
| Use Express, Hono, Elysia, or Next.js | Runnable examples |
| Build a React widget for an MCP host | MCP Apps quickstart |
For AI agents
Give your AI assistant llms.txt
for the documentation index or
llms-full.txt
for the complete documentation.
Packages
Install Toolgrain libraries at the same version. Start with mcp and the
transport package your application needs; add authorization when you need it.
| Package | Purpose |
|---|---|
| @toolgrain/mcp | Tools, servers, validation, rich results, and context |
| @toolgrain/node | Stdio, managed HTTP, and Node HTTP handlers |
| @toolgrain/http | Web Request/Response handlers |
| @toolgrain/jwt | JWT access-token verification |
| @toolgrain/clerk | Clerk OAuth access-token verification |
| @toolgrain/react | Native MCP Apps browser lifecycle and typed React hooks |
| @toolgrain/protocol | Pinned MCP wire types and version constants |
Support and scope
Stable packages are available on npm
under latest. Install the same version across Toolgrain libraries.
| Requirement | Supported |
|---|---|
| Module format | ESM |
| Node.js | ^24.20.0 |
| Bun applications | >=1.4.4 <2 |
| TypeScript | 5.5.4+ with strict mode |
| Zod | ^4.6.6, Classic or Mini |
| MCP | 2026-07-28 and initialization-based 2025-06-18 |
Node 26 is preview. Repository tooling uses Bun 1.3.14, separately from the application runtime. See the support policy.
Both protocol revisions share the same tool API over stdio and HTTP. HTTP uses
independent POST requests and JSON responses. Tools can use
await ctx.reportProgress({ progress, total, message }) to send client-requested
updates; HTTP opens a request-scoped SSE response on the first update.
Fixed resources support listing and text/binary reads; see the
resource guide. Native MCP Apps
and typed React widgets require Toolgrain 0.3.0 or later; see the
MCP Apps guide and
React example. Resource templates,
sessions, resumability, prompts, elicitation, and
subscriptions are outside the current implementation. Check the
client verification notes and roadmap
for tested flows and planned work.
Contribute
Bug reports, documentation improvements, and focused proposals are welcome. Read CONTRIBUTING for setup, checks, and release records, and follow the Code of Conduct. For vulnerabilities, use the private contact in SECURITY.
License
toolgrain MCP questions
How do I add toolgrain MCP to Claude Code?
Run claude mcp add toolgrain -- npx -y @toolgrain/clerk in your terminal. Add --scope user to make it available in every project.
How do I add toolgrain MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What transports does Toolgrain support?
You can use stdio, a Node HTTP listener, or mount a Web or Node handler in your application.
Can I protect my HTTP endpoints?
Yes, you can protect HTTP endpoints using JWT or Clerk OAuth verification.
Does Toolgrain use the official MCP SDK?
No, Toolgrain implements the Model Context Protocol directly and independently of the official SDK.