Simple MCP Server

A small Node.js and TypeScript MCP server that exposes time, calculation, restricted filesystem, and public URL fetching tools over stateless Streamable HTTP.

Requirements

• Node.js 20 or newer

• npm

Related MCP server: Simple MCP Server

Setup and start

npm install
npm run build
npm start

The default MCP endpoint is http://127.0.0.1:3000/mcp. A health check is available at http://127.0.0.1:3000/health.

For explicit local configuration:

$env:MCP_WORKSPACE_ROOT = "C:\path\to\allowed\workspace"
$env:MCP_ALLOW_WRITE = "false"
$env:MCP_HTTP_HOST = "127.0.0.1"
$env:MCP_HTTP_PORT = "3000"
npm start

Tools and resources

Resources are available at server://info and workspace://config.

Configuration

Connect an external agent

For access from another machine, bind the server to all interfaces and configure a strong API key:

$env:MCP_HTTP_HOST = "0.0.0.0"
$env:MCP_HTTP_PORT = "3000"
$env:MCP_API_KEY = "replace-with-a-long-random-secret"
$env:MCP_ALLOWED_HOSTS = "mcp.example.com"
npm start

Configure a URL-based MCP client such as Codex:

[mcp_servers.simple-toolbox]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "SIMPLE_MCP_API_KEY"

Set SIMPLE_MCP_API_KEY in the Agent process environment to the same value as the server's MCP_API_KEY. For local development, use http://127.0.0.1:3000/mcp; for remote access, put the service behind an HTTPS reverse proxy. Do not expose plain HTTP or enable filesystem writes on an untrusted network.

Development

npm run dev
npm test
npm run test:smoke

npm run test:smoke builds the project, starts it on a random local port, verifies Bearer authentication, completes a Streamable HTTP MCP handshake, lists tools and resources, and calls the calculator tool.

The server is stateless: each MCP POST request creates an isolated server transport. Standalone GET/SSE and DELETE session operations return HTTP 405. This is appropriate for the current request-response tools, but not for server-initiated notifications or resumable long-running streams.

The network guard rejects localhost, private, link-local, multicast, and reserved IP address ranges. DNS rebinding protection at the outbound socket connection layer is outside this simple server's scope; deploy behind an egress proxy when stronger network isolation is required.