node-mcp-poc

A minimal Model Context Protocol server in Node.js/TypeScript. It runs over HTTP (Express + Streamable HTTP) by default, with stdio available as a fallback, and is attachable to Claude Code.

It exposes four demo tools:

Build

pnpm install
pnpm build

Related MCP server: Simple MCP Server

Run

The server reads its config from the environment (a .env file is loaded automatically — see .env.example):

pnpm start          # HTTP server on http://localhost:3219/mcp
pnpm start:stdio    # stdio transport instead

Attach to Claude Code

This repo ships a project-level .mcp.json pointing at the HTTP endpoint, so within this directory the server is picked up automatically once it's running:

{
    "mcpServers": {
        "node-poc": { "type": "http", "url": "http://localhost:3219/mcp" },
    },
}

Start the server (pnpm start), then start (or restart) a Claude Code session and try:

• "add 2 and 3"

• "echo hello"

• "what time is it in America/New_York"

• "fetch https://api.github.com/zen via node-poc"

Check it's connected with claude mcp list.

To register it from anywhere instead of relying on .mcp.json:

# HTTP (server must already be running)
claude mcp add --transport http node-poc http://localhost:3219/mcp

# or stdio (Claude Code launches the process for you)
claude mcp add node-poc -- node /ABSOLUTE/PATH/TO/node-mcp-poc/build/index.js

Remove it with:

claude mcp remove node-poc

Develop / debug

pnpm dev        # rebuild + node --watch
pnpm typecheck  # tsc --watch
pnpm smoke      # build + stdio client smoke test (scripts/smoke.mjs)
pnpm smoke:http # HTTP client smoke test (scripts/smoke-http.mjs)
pnpm logs       # tail logs/server.log through pino-pretty
pnpm inspect    # open the MCP Inspector against the server

Notes

• In HTTP mode each MCP session gets its own server instance, keyed by the Mcp-Session-Id header; logs go to stdout (pretty-printed when NODE_ENV=development).

• In stdio mode stdout is reserved for the JSON-RPC wire, so logs go to stderr and logs/server.log (view with pnpm logs).

• Add new tools in src/index.ts via server.registerTool(...).