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

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

Tool	Description
get_current_time	Get the current time in an IANA time zone.
calculate	Evaluate a side-effect-free mathematical expression.
read_text_file	Read a UTF-8 file under the configured workspace.
list_directory	List a directory under the configured workspace.
write_text_file	Write a UTF-8 file when MCP_ALLOW_WRITE=true.
fetch_url	Fetch a public HTTP(S) URL with SSRF, timeout, and size checks.

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

Configuration

Variable	Default	Purpose
MCP_WORKSPACE_ROOT	Current directory	Filesystem sandbox root.
MCP_ALLOW_WRITE	false	Enables write_text_file.
MCP_MAX_FILE_BYTES	1048576	Maximum file read/write size.
MCP_FETCH_TIMEOUT_MS	10000	Whole-request timeout, including redirects and body reads.
MCP_MAX_RESPONSE_BYTES	2097152	Maximum fetched response body size.
MCP_HTTP_HOST	127.0.0.1	HTTP listen address.
MCP_HTTP_PORT	3000	HTTP listen port.
MCP_HTTP_PATH	/mcp	MCP endpoint path.
MCP_API_KEY	Empty	Bearer token. Required for non-loopback listen addresses.
SIMPLE_MCP_API_KEY	Empty	Alias for MCP_API_KEY, matching the Codex client variable.
MCP_ALLOWED_HOSTS	Empty	Optional comma-separated Host header allowlist.

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.