Node.js

Run your MCP server on Node.js using Hono and the @phake/mcp Node.js adapter.

The Node.js runtime adapter is experimental. APIs may change between releases.

The fastest way to get a Node.js MCP server is the scaffold CLI, which generates a complete, working project:

bun create @phake/mcp my-mcp-app --template node-hono --install

Manual setup

1. Install dependencies

   Install @phake/mcp along with its peer dependencies for the Node.js runtime:

   npm

   npm install @phake/mcp hono @hono/node-server
   

   bun

   bun add @phake/mcp hono @hono/node-server
   
2. Define your tools

   Use defineTool from @phake/mcp to create type-safe tools with Zod schemas:

   src/tools/greet.ts

   import { z } from "zod";
   import { defineTool } from "@phake/mcp";
   
   export const greetTool = defineTool({
     name: "greet",
     title: "Greet User",
     description: "Returns a greeting for the given name",
     inputSchema: z.object({
       name: z.string().describe("Name to greet"),
     }),
     outputSchema: z.object({
       message: z.string().describe("The greeting message"),
     }),
     handler: async (args) => {
       return { message: `Hello, ${args.name}!` };
     },
   });
   

   Tool definitions are runtime-agnostic — the same defineTool call works on both Cloudflare Workers and Node.js.

3. Configure environment variables

   Create a .env file in your project root for local development:

   .env

   AUTH_STRATEGY=none
   LOG_LEVEL=debug
   PORT=3000
   

   For production, add your auth strategy variables and RS_TOKENS_ENC_KEY. See the environment variables reference for the full list.

Node.js runtime exports

The @phake/mcp/runtime/node package exports the following for use in Node.js projects:

Export	Description
buildServer(options)	Creates an McpServer instance from the MCP SDK
FileTokenStore	File-backed token store (experimental)
SqliteSessionStore	SQLite-backed session store via Drizzle ORM (experimental)

import { buildServer, FileTokenStore, SqliteSessionStore } from "@phake/mcp/runtime/node";

See Storage backends for details on the experimental stores.

The node-hono scaffold template wires up the Hono HTTP layer, auth middleware, MCP transport, and tool registration automatically. It is the recommended starting point for Node.js deployments.