DEV Community

Cover image for MCP logging and tracing using mcp-trace | ContexaAI
Akshay Galande
Akshay Galande

Posted on

MCP logging and tracing using mcp-trace | ContexaAI

#mcp #modelcontextprotocol #contexaai #ai

TL;DR: Add tracing to your MCP server in literally 3 lines of code:

import { TraceMiddleware, FileAdapter } from "mcp-trace-js";
const traceAdapter = new FileAdapter("trace.log");
const traceMiddleware = new TraceMiddleware({ adapter: traceAdapter });
// Use in your MCP server - boom, full visibility
Enter fullscreen mode Exit fullscreen mode 
npm install mcp-trace
Enter fullscreen mode Exit fullscreen mode

Now let me tell you why this matters.

The Problem Nobody Talks About

Look, I've been there. You're building an MCP server, everything seems fine in development, then you deploy it and suddenly you have no idea what's happening. Users are complaining about slow responses, tools are failing mysteriously, and you're stuck playing detective with zero visibility into what's actually going on.

When you're building with the Model Context Protocol, you're essentially creating a black box. Sure, your server handles requests and returns responses, but what happens in between? Which tools are being called? How long are they taking? What arguments are being passed? Are there patterns in the failures?

Without proper observability, you're flying blind. And trust me, that's not a fun place to be when things go wrong at 2 AM.

That's exactly why I created mcp-trace-js.

The Adapters That Actually Matter

Here's where it gets interesting. I didn't just build one way to store traces - I built adapters for the places you're actually storing data:

File Adapter - Sometimes you just want logs in a file. Perfect for development or simple deployments.

PostgreSQL Adapter - Because your data is probably already in Postgres, and querying traces with SQL is powerful as hell.

Supabase Adapter - Same as Postgres but with all the Supabase goodness if that's your thing.

Contexa Adapter - For when you want cloud-based trace analytics without the setup headache.

Console Adapter - Pretty-printed logs right in your terminal. Great for debugging.

Multi Adapter - Use multiple adapters at once. Log to file AND database. Because why not?

The Privacy Thing

Here's something most tracing tools get wrong - they log everything by default and make it hard to exclude sensitive data. I built mcp-trace-js the other way around.

Want to log tool names but not arguments? Easy:

const traceMiddleware = new TraceMiddleware({
  adapter: traceAdapter,
  logFields: {
    tool_name: true,
    tool_response: true,
    tool_arguments: false,  // Nope, keep this private
    client_id: false,       // This too
  },
});
Enter fullscreen mode Exit fullscreen mode

You control exactly what gets logged. No surprises, no accidentally logging user data you shouldn't.

Real Talk: Why This Matters

I've seen too many projects fail because the developers lost control of their systems. You build something, it works, then it scales and suddenly you don't understand your own creation anymore.

Observability isn't just about fixing bugs - it's about understanding patterns, optimizing performance, and staying in control as your system grows.

With mcp-trace-js, you can:

  • Debug faster - See exactly what tool calls are failing and why
  • Optimize performance - Identify slow operations and bottlenecks
  • Understand usage patterns - Know which tools are popular and which aren't
  • Monitor in production - Get alerts when things go wrong, not when users complain

The Technical Details (If You Care)

It's built with TypeScript, so you get full type safety and IntelliSense. The trace format is JSON, so you can query it however you want. It's composable, so you can use multiple adapters. It's configurable, so you can log exactly what you need.

But honestly? The technical details don't matter if it doesn't solve your problem. And the problem it solves is simple: visibility into your MCP servers.

Getting Started 

npm install mcp-trace
Enter fullscreen mode Exit fullscreen mode

Check out the examples in the repo. There's a basic usage example, an MCP server integration, and even a complete HTTP server setup. Pick what fits your use case and go.

The documentation is straightforward, the API is clean, and it just works.

Why I'm Sharing This

I built mcp-trace-js because I needed it. I was tired of debugging MCP servers without proper visibility. I was tired of guessing what was going wrong.

If you're building with MCP, you probably need this too. Don't wait until you're debugging a production issue at 2 AM to realize you need proper tracing.

The repo is at https://github.com/ContexaAI/mcp-trace-js. MIT licensed, contributions welcome, issues and PRs encouraged.

Stop flying blind. Start tracing your MCP servers properly.

Found this useful? Give the repo a star and let me know what you think. And if you build something cool with mcp-trace-js, I'd love to hear about it.

Top comments (0)