Logging

The log object lets you emit structured messages from anywhere in your handler code. Log output appears in two places depending on where your MCP server is running:

• Local dev (mctx-dev) — printed to the terminal after each request completes.
• Production — visible in the platform's log viewer.

Log levels

@mctx-ai/mcp follows RFC 5424 severity levels, from lowest to highest:

import { log } from "@mctx-ai/mcp";

log.debug("detailed trace for debugging");
log.info("normal operational message");
log.notice("significant event, not an error");
log.warning("something unexpected, but recoverable");
log.error("an error that affects this request");
log.critical("serious failure requiring immediate attention");
log.alert("action must be taken right now");
log.emergency("system is unusable");

In practice, most handlers use log.debug, log.info, and log.warning. Reserve log.error and above for genuine failures.

What to log

Each log.* method accepts any JSON-serializable value:

// A plain string
log.info("Starting export");

// An object with structured fields
log.info({ userId: ctx?.userId, action: "export", format: args.format });

// An error with context
log.error({ error: err.message, tool: "export", args });

Structured objects are easier to search and filter in the log viewer than concatenated strings.

Dev server output

When you run mctx-dev, log output is buffered during the request and printed to the terminal after the response is sent. You see all log entries for a request grouped together, with the request method and tool name shown above them:

POST /v1  tools/call  greet  200  12ms
  [debug] Greeting Alice with: Hello
  [info]  { userId: "usr_abc123", action: "greet" }

The dev server also prints a slow-tool warning if a tools/call request takes longer than 1000ms.

Production logs

In production, logs flow through the mctx platform and are accessible in the dashboard log viewer. See MCP Server Logs for how to view, filter, and search your production log output.

Buffer helpers

The log buffer is managed by the framework automatically. You rarely need to touch it directly.

Two exports exist for advanced use cases:

import { getLogBuffer, clearLogBuffer } from "@mctx-ai/mcp";

// Returns a copy of buffered log entries as LogNotification[]
const entries = getLogBuffer();

// Empties the buffer
clearLogBuffer();

These are useful if you need to inspect or forward log data inside a handler — for example, capturing logs from a sub-operation and including them in the tool's response. The server calls clearLogBuffer() automatically after each request, so you do not need to manage the buffer in normal handler code.

Example

A tool that logs before and after an external fetch:

import { createServer, T, log } from "@mctx-ai/mcp";

const server = createServer();

const fetchPage = async (args) => {
  log.info({ url: args.url, tool: "fetch-page" });

  let response;
  try {
    response = await fetch(args.url);
  } catch (err) {
    log.error({ error: err.message, url: args.url });
    throw new Error(`Failed to fetch ${args.url}: ${err.message}`);
  }

  const text = await response.text();
  log.debug({ url: args.url, status: response.status, bytes: text.length });

  return text.slice(0, 2000);
};
fetchPage.description = "Fetch the text content of a URL";
fetchPage.input = {
  url: T.string({ required: true, description: "URL to fetch", format: "uri" }),
};
fetchPage.annotations = {
  readOnlyHint: true,
  destructiveHint: false,
  openWorldHint: true,
  idempotentHint: true,
};

server.tool("fetch-page", fetchPage);

export default { fetch: server.fetch };

Running mctx-dev and calling this tool prints the log entries to your terminal grouped under the request that produced them.

Next steps

• MCP Server Logs — view and filter production logs in the dashboard
• Testing — run your handlers in unit tests and inspect behavior
• Framework API Reference — full type definitions for log, LogNotification, and LogLevel

See something wrong? Report it or suggest an improvement — your feedback helps make these docs better.