Custom Stdio MCP Server (Node.js Example)

Wiring a Custom Stdio Server

Stdio is the default transport for MCP. The client spawns your binary, writes JSON-RPC frames to its stdin, and reads frames from its stdout. Anything you write to stderr is captured into the client's MCP debug log.

Config

{
  "mcpServers": {
    "my-tools": {
      "command": "node",
      "args": ["/Users/me/code/my-mcp-server/dist/index.js"],
      "env": {
        "LOG_LEVEL": "info",
        "API_BASE": "https://api.internal.example.com"
      }
    }
  }
}

Why an absolute path

Relative paths resolve against the client's working directory, not your terminal's. For Claude Desktop that's usually / on macOS, which means ./dist/index.js will fail to launch. Use pwd in your project to grab the absolute path and paste it into args.

Building a minimal server

The official SDK makes this short:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({ name: "my-tools", version: "0.1.0" }, {
  capabilities: { tools: {} },
});

server.setRequestHandler(/* ... */);
await server.connect(new StdioServerTransport());

Compile with tsc to a dist/ folder and point the config at the entry file.

Passing env safely

Anything in env is set on the child process. Use this for config that varies per machine (LOG_LEVEL, API_BASE) and for secrets (API_TOKEN, DATABASE_URL). The generator's secret-warning banner activates when it detects any non-empty env value.

Debugging

Write to process.stderr from your server and check Claude Desktop's logs at ~/Library/Logs/Claude/mcp*.log — see debugging logs for the full workflow.