MCP Server Template with Modular Tools

A Node.js implementation of an MCP (Model Context Protocol) server built on the 2026-07-28 specification: stateless, per-request metadata, Streamable HTTP.

Features

MCP 2026-07-28 only: stateless core, server/discover, subscriptions/listen, resultType, cacheable list results, request-metadata headers — no handshake-era code paths to maintain
Dynamic Tool Loading: automatically discovers and loads tools from /tools
Typed tool results: outputSchema + structuredContent, input validation
API Key Authentication with an RFC 9728 WWW-Authenticate challenge
Sample Tools: calculator and timestamp for demonstration

What changed in 2026-07-28

The 2026-07-28 revision made MCP a stateless request/response protocol. This server implements that revision and nothing older — a client on 2025-11-25 or earlier gets a 400 telling it which version to use. If you are pointing an existing client at this server, these are the changes that matter:

Removed	Replacement
`initialize` / `notifications/initialized`	Per-request `_meta` on every request
`Mcp-Session-Id` header, `DELETE /mcp`	No protocol sessions — pass explicit handles as tool arguments
`GET /mcp` SSE stream, `resources/subscribe`	`subscriptions/listen` (one long-lived POST-response stream)
`ping`, `logging/setLevel`, `notifications/roots/list_changed`	Removed; log level is per-request via `_meta`
`Last-Event-ID` resumability, SSE event ids	None — re-issue the request with a new id
Server-initiated `sampling/createMessage`, `elicitation/create`, `roots/list`	Multi Round-Trip Requests (`resultType: "input_required"`)
JSON-RPC batching	One JSON-RPC message per POST

Added: server/discover, the required resultType field on every result, ttlMs/cacheScope on list results, required MCP-Protocol-Version / Mcp-Method / Mcp-Name headers, x-mcp-header tool parameters, and the -32020/-32021/-32022 error codes. Roots, Sampling and Logging are now deprecated and are not advertised by this server.

Quick Start

Install dependencies:

npm install

Set up environment:

cp .env.example .env

Start the server:

npm start

Run the conformance tests:

npm test

Server runs on http://127.0.0.1:3202.

🔐 Authentication

An API key is required for all requests (except /health):

curl -H "Authorization: Bearer your-api-key" http://127.0.0.1:3202/health

X-API-Key and an ?api_key= query parameter also work, but the Authorization header is what MCP clients send. A 401 carries a WWW-Authenticate: Bearer challenge. Set MCP_AUTHORIZATION_SERVER to advertise a real OAuth 2.0 authorization server — the challenge then points at /.well-known/oauth-protected-resource (RFC 9728), which is what MCP clients probe. Client credentials must be keyed by issuer, and new clients should prefer Client ID Metadata Documents over Dynamic Client Registration, which this revision deprecates.

📡 Talking to the server

Every request carries its protocol version, client identity and capabilities in params._meta, and mirrors method (and name/uri) into HTTP headers. A mismatch between headers and body is rejected with 400 and error -32020.

Discovery

curl -X POST http://127.0.0.1:3202/mcp -H "Authorization: Bearer your-api-key" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "MCP-Protocol-Version: 2026-07-28" -H "Mcp-Method: server/discover" -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'

Calling a tool

tools/call additionally requires the Mcp-Name header, matching params.name:

curl -X POST http://127.0.0.1:3202/mcp -H "Authorization: Bearer your-api-key" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "MCP-Protocol-Version: 2026-07-28" -H "Mcp-Method: tools/call" -H "Mcp-Name: calculator" -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"calculator","arguments":{"operation":"multiply","operand1":7,"operand2":8},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resultType": "complete",
    "content": [{ "type": "text", "text": "{\"operation\":\"multiply\",\"operands\":[7,8],\"result\":56}" }],
    "structuredContent": { "operation": "multiply", "operands": [7, 8], "result": 56 },
    "_meta": { "io.modelcontextprotocol/serverInfo": { "name": "mcp-server", "version": "2.0.0" } }
  }
}

Add "progressToken" to _meta and send Accept: text/event-stream to get the response as a stream with notifications/progress ahead of the result.

Change notifications

curl -N -X POST http://127.0.0.1:3202/mcp -H "Authorization: Bearer your-api-key" -H "Content-Type: application/json" -H "Accept: text/event-stream" -H "MCP-Protocol-Version: 2026-07-28" -H "Mcp-Method: subscriptions/listen" -d '{"jsonrpc":"2.0","id":1,"method":"subscriptions/listen","params":{"notifications":{"toolsListChanged":true},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

The first message is notifications/subscriptions/acknowledged, echoing the filters the server will honour. Every message on the stream is tagged with io.modelcontextprotocol/subscriptionId. Run with MCP_WATCH_TOOLS=true and edit a file in tools/ to see notifications/tools/list_changed arrive.

Closing the stream is the cancellation signal — there is no DELETE.

🛠️ Available Tools

Tool	Description
`calculator`	Add, subtract, multiply, divide — returns `structuredContent`
`timestamp`	Current time as ISO 8601, Unix epoch, or human-readable

⚙️ Creating Your Tools

1. Tool File Structure

Create tools/your-tool.js:

const TOOL_DEFINITION = {
    name: "your_tool",
    title: "Your Tool",
    description: "What your tool does",
    inputSchema: {
        type: "object",
        properties: {
            param1: { type: "string", description: "Parameter description" }
        },
        required: ["param1"],
        additionalProperties: false
    },
    // Optional but recommended: lets clients validate structuredContent.
    outputSchema: {
        type: "object",
        properties: { result: { type: "string" } },
        required: ["result"]
    }
};

async function execute(args = {}, context = {}) {
    const { param1 } = args;

    // context.reportProgress({ progress, total, message }) streams progress
    // when the client sent a progressToken.
    // context.signal aborts when the client closes the stream.
    // context.clientInfo / context.clientCapabilities describe the caller.

    const structuredContent = { result: `Processed: ${param1}` };

    return {
        content: [{ type: "text", text: JSON.stringify(structuredContent) }],
        structuredContent
    };
}

module.exports = { definition: TOOL_DEFINITION, execute };

Arguments are validated against inputSchema before execute runs. Throwing from execute produces a tool execution error (isError: true) rather than a JSON-RPC error, so the model can self-correct.

2. Auto-Loading

Save the file in /tools and restart the server (or set MCP_WATCH_TOOLS=true to hot-reload and notify subscribers).

3. Stateful tools

MCP has no protocol-level session. If a tool needs state across calls, return an opaque handle and accept it as an argument on later calls — document its lifetime in the tool description so the model knows when to create a new one.

4. Asking the client for input (MRTR)

Instead of sending a server-initiated elicitation/create request, return an input-required result and let the client retry:

return {
    resultType: "input_required",
    inputRequests: {
        github_login: {
            method: "elicitation/create",
            params: {
                mode: "form",
                message: "Please provide your GitHub username",
                requestedSchema: {
                    type: "object",
                    properties: { name: { type: "string" } },
                    required: ["name"]
                }
            }
        }
    },
    // Anything you need to resume; it comes back on the retry.
    requestState: "..."
};

The retry arrives as a new tools/call with context.inputResponses and context.requestState populated.

5. Exposing a parameter as an HTTP header

Annotate a primitive, statically reachable property with x-mcp-header so intermediaries can route on it without parsing the body:

region: { type: "string", description: "...", "x-mcp-header": "Region" }

Conforming clients then send Mcp-Param-Region: us-west1, and the server rejects any request where the header and the argument disagree. Never annotate secrets — header values are visible to every intermediary on the path.

🔗 MCP Client Integration

{
  "mcpServers": {
    "template": {
      "type": "http",
      "url": "http://127.0.0.1:3202/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

📁 Layout

mcp-server.js        Express app, routing, request validation, dispatch
lib/protocol.js      Version constants, _meta keys, error codes, message builders
lib/headers.js       Request-metadata headers, base64 sentinel, x-mcp-header
lib/schema.js        Tool argument validation
lib/sse.js           SSE response streams (no resumability, per spec)
lib/subscriptions.js subscriptions/listen stream management
lib/security.js      Origin validation, API key auth, RFC 9728 metadata
tools/               Auto-loaded tools
test/                Protocol conformance tests

Endpoints

Endpoint	Purpose
`POST /mcp`	The MCP endpoint — the only method it accepts
`GET /mcp`, `DELETE /mcp`	`405`: the standalone SSE stream and session termination are gone
`GET /health`	Status, protocol version, open subscriptions
`GET /tools/config`	Tool definitions for wiring into an agent config
`GET /.well-known/oauth-protected-resource`	RFC 9728 metadata, when configured

License

This server is provided as-is for demonstration purposes. Please review and enhance security measures before production use.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
lib		lib
test		test
tools		tools
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
bun.lock		bun.lock
mcp-server.js		mcp-server.js
package-lock.json		package-lock.json
package.json		package.json

Navigation Menu

Uh oh!

Repository files navigation

MCP Server Template with Modular Tools

Features

What changed in 2026-07-28

Quick Start

🔐 Authentication

📡 Talking to the server

Discovery

Calling a tool

Change notifications

🛠️ Available Tools

⚙️ Creating Your Tools

1. Tool File Structure

2. Auto-Loading

3. Stateful tools

4. Asking the client for input (MRTR)

5. Exposing a parameter as an HTTP header

🔗 MCP Client Integration

📁 Layout

Endpoints

License

About

Releases

Packages

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

MCP Server Template with Modular Tools

Features

What changed in 2026-07-28

Quick Start

🔐 Authentication

📡 Talking to the server

Discovery

Calling a tool

Change notifications

🛠️ Available Tools

⚙️ Creating Your Tools

1. Tool File Structure

2. Auto-Loading

3. Stateful tools

4. Asking the client for input (MRTR)

5. Exposing a parameter as an HTTP header

🔗 MCP Client Integration

📁 Layout

Endpoints

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages