NitroStack Logo
/getting started
/quickstart

Quickstart

This hands-on guide walks you through building and connecting your first NitroStack Model Context Protocol (MCP) server in under 10 minutes.

[!IMPORTANT] Prerequisites: Node.js 20.x or later (LTS recommended) and npm 9.x or later.

Step 1: Scaffold Your Project

Initialize a new NitroStack project using the official CLI:

Bash
npx @nitrostack/cli init my-server
cd my-server

During initialization, the CLI sets up a modular project structure with sample tools, resources, prompts, and an interactive Next.js widget development server.

Text
my-server/
├── src/
│   ├── index.ts              # Server bootstrap and entry point
│   ├── app.module.ts         # Root application module
│   └── modules/
│       └── calculator/       # Sample feature module
│           ├── calculator.module.ts
│           ├── calculator.tools.ts
│           ├── calculator.resources.ts
│           └── calculator.prompts.ts
├── src/widgets/              # React/Next.js interactive widget components
├── package.json
└── tsconfig.json

Step 2: Start the Development Server

Run the development server with hot reloading enabled:

Bash
npm run dev

Expected terminal output:

Text
✔ MCP Server running at http://localhost:3000/mcp (HTTP / SSE)
✔ Health checks active at http://localhost:3000/health
✔ Widget development server running at http://localhost:3001

The MCP server listens on port 3000, while interactive widgets are served from port 3001.

Step 3: Call Your First Tool

Test the server immediately via JSON-RPC or connect using NitroStudio or the MCP Inspector.

Test via Terminal (JSON-RPC)

In a separate terminal window, send a tools/call request to the server:

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

Expected response:

JSON
{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"result\":18,\"expression\":\"15 add 3 = 18\"}"
      }
    ]
  },
  "id": 1
}

Test in NitroStudio or MCP Inspector

  1. Open NitroStudio desktop or navigate to MCP Inspector.
  2. Connect to server transport: Streamable HTTP (http://localhost:3000/mcp).
  3. Select calculate, provide parameters a: 10, b: 5, operation: "multiply", and click Run.
  4. View the structured calculation result alongside the rendered calculator widget.

Step 4: Add Your Own Tool

Open src/modules/calculator/calculator.tools.ts and add a new tool method:

Typescript
import { Tool, ExecutionContext } from '@nitrostack/core';
import { z } from 'zod';

export class CalculatorTools {
  // Existing calculate tool...

  @Tool({
    name: 'format_currency',
    description: 'Format a monetary number into standard currency string',
    inputSchema: z.object({
      amount: z.number().describe('Amount to format'),
      currency: z.string().default('USD').describe('Three-letter currency code (USD, EUR, GBP)'),
      locale: z.string().default('en-US').describe('Locale string'),
    }),
  })
  async formatCurrency(
    input: { amount: number; currency: string; locale: string },
    ctx: ExecutionContext
  ) {
    const formatted = new Intl.NumberFormat(input.locale, {
      style: 'currency',
      currency: input.currency,
    }).format(input.amount);

    return {
      amount: input.amount,
      formatted,
      currency: input.currency,
    };
  }
}

Save the file. The development server hot-reloads automatically. Your new tool is immediately available in the MCP tools list.

Step 5: Connect to an AI Client

Configure your AI assistant to communicate with your server:

Cursor Configuration

Create or update .cursor/mcp.json in your workspace:

JSON
{
  "mcpServers": {
    "my-server": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Or run the CLI setup shortcut:

Bash
npx @nitrostack/cli cursor

Your tools (calculate, format_currency) will appear in Cursor Composer and Agent chats.

Next Steps

Documentation Home•View All Docs•GitHub