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