How to log from an MCP server (logging is deprecated)

// Survives. The reader skips the line it cannot parse, and the call returns.
console.log("working...");

// Breaks. With no newline this prefix is glued onto the front of the next
// JSON-RPC message, that line fails to parse, and the response is lost.
process.stdout.write("working...");

// Structured logging for an MCP server. Every line goes to stderr, because on
// stdio the stdout stream belongs to the protocol.
const LEVELS = ["debug", "info", "warning", "error"] as const;
type Level = (typeof LEVELS)[number];

// An unrecognized MCP_LOG_LEVEL falls back to "info" rather than logging
// everything, so a typo in a client config cannot flood the log.
const configured = process.env.MCP_LOG_LEVEL as Level | undefined;
const threshold = LEVELS.indexOf(
  configured && LEVELS.includes(configured) ? configured : "info"
);

// Field names whose values must never reach a log file.
const SECRET_KEY = /^(authorization|api[-_]?key|token|password|secret)$/i;

function redact(fields: Record<string, unknown>): Record<string, unknown> {
  const safe: Record<string, unknown> = {};
  for (const [key, value] of Object.entries(fields)) {
    if (value === undefined) continue; // an absent field is not a redacted one
    safe[key] = SECRET_KEY.test(key) ? "[redacted]" : value;
  }
  return safe;
}

export function log(
  level: Level,
  message: string,
  fields: Record<string, unknown> = {}
): void {
  if (LEVELS.indexOf(level) < threshold) return;
  // One JSON object per line: greppable by a human, parseable by a log shipper.
  const line = JSON.stringify({
    ts: new Date().toISOString(),
    level,
    message,
    ...redact(fields),
  });
  process.stderr.write(line + "\n");
}

import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { log } from "./logger.ts";

function createServer() {
  const server = new McpServer(
    { name: "log-demo", version: "1.0.0" },
    { capabilities: { tools: {} } }
  );

  server.registerTool(
    "lookup_order",
    {
      title: "Look up order",
      description: "Fetch the status of an order by its id.",
      inputSchema: z.object({
        orderId: z.string(),
        apiKey: z.string().optional(),
      }),
      outputSchema: z.object({ orderId: z.string(), status: z.string() }),
    },
    async ({ orderId, apiKey }) => {
      const startedAt = Date.now();
      // apiKey is passed to redact() by name and never reaches the log file.
      log("debug", "tool.start", { tool: "lookup_order", orderId, apiKey });

      if (!/^ord_[a-z0-9]+$/.test(orderId)) {
        log("error", "tool.rejected", {
          tool: "lookup_order",
          orderId,
          reason: "malformed order id",
        });
        return {
          content: [{ type: "text", text: `unknown order: ${orderId}` }],
          isError: true,
        };
      }

      const output = { orderId, status: "shipped" };
      log("info", "tool.ok", {
        tool: "lookup_order",
        orderId,
        ms: Date.now() - startedAt,
      });
      return {
        content: [{ type: "text", text: JSON.stringify(output) }],
        structuredContent: output,
      };
    }
  );

  return server;
}

serveStdio(createServer);
log("info", "server.ready", { transport: "stdio", pid: process.pid });

{"ts":"2026-08-30T09:14:02.857Z","level":"info","message":"server.ready","transport":"stdio","pid":47612}
{"ts":"2026-08-30T09:14:02.869Z","level":"debug","message":"tool.start","tool":"lookup_order","orderId":"ord_1042","apiKey":"[redacted]"}
{"ts":"2026-08-30T09:14:02.869Z","level":"info","message":"tool.ok","tool":"lookup_order","orderId":"ord_1042","ms":0}
{"ts":"2026-08-30T09:14:02.870Z","level":"debug","message":"tool.start","tool":"lookup_order","orderId":"nope"}
{"ts":"2026-08-30T09:14:02.870Z","level":"error","message":"tool.rejected","tool":"lookup_order","orderId":"nope","reason":"malformed order id"}

/** Drives the server over a real stdio connection and asserts three things:
 *  the tools still work, the log lines are parseable JSON on stderr, and the
 *  secret never lands in the log. Run it with: node test.ts */
import assert from "node:assert/strict";
import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";

type LogLine = { level: string; message: string; [key: string]: unknown };

// Spawn the server at a given log level, exercise both tool paths, and hand
// back everything it wrote to stderr.
async function run(level: string): Promise<{ lines: LogLine[]; raw: string }> {
  // stderr: "pipe" hands us the server's log stream instead of letting it
  // pass through to our own terminal.
  const transport = new StdioClientTransport({
    command: "node",
    args: ["server.ts"],
    env: { ...process.env, MCP_LOG_LEVEL: level },
    stderr: "pipe",
  });

  let raw = "";
  const client = new Client({ name: "log-test", version: "1.0.0" });
  await client.connect(transport);
  transport.stderr?.on("data", (chunk: Buffer) => (raw += chunk.toString()));

  const ok = await client.callTool({
    name: "lookup_order",
    arguments: { orderId: "ord_1042", apiKey: "sk-live-do-not-log-me" },
  });
  assert.deepEqual(ok.structuredContent, {
    orderId: "ord_1042",
    status: "shipped",
  });

  const bad = await client.callTool({
    name: "lookup_order",
    arguments: { orderId: "'; DROP TABLE orders --" },
  });
  assert.equal(bad.isError, true);

  await new Promise((resolve) => setTimeout(resolve, 250)); // let stderr flush
  await client.close();

  // Every line must be a complete JSON object. A partial or non-JSON line
  // means something wrote to the stream that was not the logger.
  const lines = raw
    .trim()
    .split("\n")
    .filter(Boolean)
    .map((line) => JSON.parse(line) as LogLine);
  return { lines, raw };
}

// 1. At debug level every stage is recorded, and the tool calls above both
//    returned correct results, which only happens if stdout stayed clean.
const debug = await run("debug");
assert.ok(debug.lines.some((l) => l.message === "tool.start" && l.level === "debug"));
assert.ok(debug.lines.some((l) => l.message === "tool.ok" && l.orderId === "ord_1042"));
assert.ok(debug.lines.some((l) => l.message === "tool.rejected" && l.level === "error"));

// 2. The API key was logged by name and came out redacted.
assert.ok(!debug.raw.includes("sk-live-do-not-log-me"));
assert.ok(debug.lines.some((l) => l.apiKey === "[redacted]"));

// 3. At error level the debug and info lines are gone, the error line remains.
const errors = await run("error");
assert.equal(errors.lines.filter((l) => l.level !== "error").length, 0);
assert.ok(errors.lines.some((l) => l.message === "tool.rejected"));

console.log("ALL CHECKS PASSED");

npm install @modelcontextprotocol/[email protected] @modelcontextprotocol/[email protected] [email protected]
node test.ts
# ALL CHECKS PASSED