Quickstart

Create a project

Run the CLI's init command. The --template flag picks the Starter template, a small calculator server built for learning.

npx @nitrostack/cli init my-server --template typescript-starter
cd my-server

The CLI asks for an optional description and author, copies the template, and installs dependencies. If you leave out --template, you can choose from all templates interactively.

Start the server

Run the project's start script:

npm start

It builds your TypeScript and starts your MCP server over HTTP at http://localhost:3000/mcp. When the server is ready, leave this terminal running.

Call your first tool

The Starter template ships with a calculate tool. Pick one way to call it.

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"calculate","arguments":{"a":15,"b":3,"operation":"add"}}}'

npx @nitrostack/cli cursor

Add your own tool (optional)

Now add a tool of your own: say_hello, which takes a name and returns a greeting. In NitroStack, a tool is a method on a class, marked with the @Tool decorator. The Starter template keeps its tools in the CalculatorTools class, so that's where the new method goes.

Open src/modules/calculator/calculator.tools.ts and add the sayHello method inside the CalculatorTools class, below the existing calculate method:

import { ToolDecorator as Tool, Widget, ExecutionContext, z } from '@nitrostack/core';

export class CalculatorTools {
  // ...the existing calculate tool stays as it is

  @Tool({
    name: 'say_hello',
    description: 'Greet someone by name',
    inputSchema: z.object({
      name: z.string().describe('Who to greet'),
    }),
  })
  async sayHello(input: { name: string }, ctx: ExecutionContext) {
    return { message: `Hello, ${input.name}!` };
  }
}

Here is what each part does:

• @Tool({ ... }) registers the method as an MCP tool. Clients see it under name (say_hello), and the AI model reads description to decide when to call it.
• inputSchema describes the arguments with Zod: one string called name. NitroStack checks every call against this schema, so invalid input never reaches your method. The .describe() text tells the model what to pass.
• async sayHello(input, ctx) is the handler. input holds the validated arguments, and ctx is the execution context with a logger and request details.
• The return value is sent back to the client as the tool's result: here, an object with a message.

Save the file, then stop the server and run npm start again. say_hello appears in the tool list next to calculate. Call it with { "name": "Ada" } and you get back Hello, Ada!.