mcp-trace

Flexible, pluggable tracing middleware for Model Context Protocol (MCP) servers in JavaScript/TypeScript. Log every request, tool call, and response to local files, PostgreSQL, Supabase, Contexa, console, OTLP, or your own backend—with full control over what gets logged.

Table of Contents

• Features
• Quickstart
• Basic Usage
• Feature Usage
  • Configurable Logging
  • Request-Level Control
  • PII Redaction
  • User Identification
  • Production-Ready Features
• Contexa Adapter
• Other Adapters
  • File Adapter
  • Console Adapter
  • PostgreSQL Adapter
  • Supabase Adapter
  • OTLP Adapter
  • Multi-Adapter Example
• Requirements
• Contributing
• License
• Links & Acknowledgements

Features

• 📦 Plug-and-play: Add tracing to any MCP server in seconds
• 🗃️ Pluggable adapters: Log to file, PostgreSQL, Supabase, Contexa, console, OTLP, or your own
• 🛠️ Configurable logging: Enable/disable fields (tool args, responses, client ID, etc.)
• 🧩 Composable: Use multiple adapters at once
• 📝 Schema-first: All traces stored as JSON for easy querying
• 🔒 Privacy-aware: Control exactly what gets logged
• ⚡ TypeScript support: Full type safety and IntelliSense
• 🛡️ Production-ready: Comprehensive error handling and memory management
• 🔧 Robust validation: Configuration validation with descriptive error messages
• 🧹 Automatic cleanup: Prevents memory leaks with timeout management
• 🌐 OpenTelemetry support: Native OTLP integration for observability platforms

Quickstart

Installation

npm install mcp-trace

Minimal Example

import { TraceMiddleware, FileAdapter } from "mcp-trace-js";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

// Create your MCP server
const server = new McpServer({ name: "my-server", version: "1.0.0" });

// Set up tracing
const traceAdapter = new FileAdapter("trace.log");
const traceMiddleware = new TraceMiddleware({ adapter: traceAdapter });

// Initialize tracing with your server
traceMiddleware.init(server);

// Your server is now fully traced!

Basic Usage

Streamable HTTP Server

See example/streamable-http-server.ts for a complete MCP server using Streamable HTTP transport with tracing.

npm run example:streamable-http

This example demonstrates:

• Setting up an MCP server with Streamable HTTP transport
• Registering tools with tracing integration
• Handling HTTP requests with proper tracing
• Graceful shutdown with trace flushing

The server includes:

• Addition tool: Adds two numbers
• Search tool: Simulates search functionality
• Health check endpoint: /health
• MCP endpoint: /mcp (GET and POST)
• Tracing: All requests and tool calls are traced to streamable-http-trace.log

Feature Usage

Configurable Logging

Control exactly which fields are logged by passing a logFields dictionary to TraceMiddleware. By default, all fields are logged unless set to false.

Available fields:

• type, method, timestamp, session_id, request_id, client_id, duration
• tool_name, tool_arguments, tool_response, tool_response_structured

**Example: Only log tool name and response, hide arguments

... View full README on GitHub