box7e7/mcp_node_server_stateless

MCP Node Server - Stateless Mode

A simple Model Context Protocol (MCP) server implementation using HTTP streaming in stateless mode with a get_time tool.

Features

• Stateless HTTP Transport: Creates a new transport for each request, preventing session conflicts
• Bearer Token Authentication: Secure API access using Bearer tokens
• Get Time Tool: Retrieve current time with timezone and format options

Prerequisites

• Node.js (v18 or higher recommended)
• npm or yarn

Installation

1. Install dependencies:

npm install

2. Create a .env file from the example:

cp .env.example .env

3. Update the .env file with your configuration:

PORT=3000
API_TOKEN=your-secure-token-here

Usage

Start the Server

npm start

Or for development with auto-reload:

npm run dev

The server will start on http://localhost:3000/mcp (or the port specified in your .env file).

Available Tools

get_time

Get the current date and time with optional timezone support.

Parameters:

• timezone (optional): Timezone string (e.g., "America/New_York", "UTC", "Asia/Tokyo")
• format (optional): Output format - "iso" (default), "locale", or "unix"

Example Response:

{
  "time": "2025-10-11T08:21:16.000Z",
  "timezone": "UTC",
  "format": "iso",
  "timestamp": 1760155276000
}

API Endpoints

POST /mcp

Main endpoint for MCP tool calls and requests.

GET /mcp

Health check and server information.

DELETE /mcp

Session cleanup (stateless mode).

Authentication

All requests require a Bearer token in the Authorization header:

curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer test-token-12345" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Architecture

This server uses stateless mode which means:

• A new transport is created for each HTTP request
• No session state is maintained between requests
• Ideal for serverless deployments and load-balanced environments
• Compatible with OpenAI's MCP connection management

Adding New Tools

To add a new tool, register it with the mcpServer instance in server.js:

mcpServer.tool(
  'tool_name',
  'Tool description',
  {
    param1: z.string().describe('Parameter description'),
  },
  async ({ param1 }) => {
    // Tool implementation
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ result: 'value' })
      }]
    };
  }
);

Environment Variables

License

Private - Internal Use Only