@awarecorp/mcp-logger

Unified MCP Observability Solution - Monitor your Model Context Protocol servers with zero configuration.

Aware Corp

🎯 Overview

@awarecorp/mcp-logger provides comprehensive observability for MCP servers in two ways:

• SDK: Direct integration for custom MCP servers
• CLI: Zero-code wrapper for existing MCP packages

All telemetry data is sent to OpenTelemetry-compatible endpoints with automatic request-response pairing.

📦 Installation

npm install @awarecorp/mcp-logger

🚀 Quick Start

SDK Mode

Instrument your MCP server with one line of code:

import { trace } from "@awarecorp/mcp-logger";

trace(server, {
  apiKey: "YOUR_API_KEY",
  serviceName: "my-mcp-server",
});

CLI Mode

Wrap any existing MCP server without code changes:

npx @awarecorp/mcp-logger \
  -k YOUR_API_KEY \
  -s my-server \
  npx your-mcp-server

📋 Features

Core Capabilities

• Automatic Request-Response Pairing: Single span per request-response cycle with intelligent message correlation
• Notification Support: Tracks both client→server and server→client notifications
• Selective Method Tracking: Configurable filtering to track only relevant methods (excludes noisy notifications like notifications/initialized)
• Custom Event Logging: Add context-aware logs within request handlers
• Enhanced Error Handling: Robust error serialization for complex error objects
• Custom OTLP Endpoint: Send traces to any OTLP/HTTP compatible observability backend
• Transport Support: stdio and SSE (Server-Sent Events)
• Zero Configuration: Works out of the box with sensible defaults

Telemetry Data

All spans include:

• Request/response timestamps and payloads
• Method name and parameters
• Tool names and arguments (for tools/call)
• Custom events and logs
• Error details (if any)
• Duration metrics
• CLI server information (command, args, env)

Data Format

Optimized for Elasticsearch with flat structure:

• mcp.request.method / mcp.response.method: Method names for request/response
• mcp.source: sdk or cli
• mcp.transport: stdio or sse
• mcp.duration_ms: Request duration
• mcp.tool.name: Tool name (tools/call only)
• mcp.request.params / mcp.response.result: Request/response payloads
• mcp.error.message: Enhanced error serialization (no more [object Object])
• mcp.events: Custom log entries (JSON array)
• mcp.cli.server: CLI execution info (JSON object)

🔧 SDK API

trace(server, options)

Enable automatic instrumentation on an MCP server.

Parameters:

• server: MCP Server instance
• options.apiKey: API key for authentication (required)
  • Currently accepts any string value for testing purposes
  • For production use, sign up at Aware to get your API key
• options.serviceName: Service identifier (optional, auto-generated if omitted)
• options.endpoint: Custom OTLP endpoint (optional, default: https://aware.mcypher.com/v1/traces)
  • Accepts any OTLP/HTTP compatible endpoint URL
  • Use this to send traces to your own observability backend (e.g., Jaeger, Grafana, etc.)
• options.debug: Enable debug logging (optional, default: false)

Returns: void

trace.addLog(entry)

Add custom log entries within request handlers.

Parameters:

• entry.level: Log level (info | warn | error)
• entry.message: Log message (required)
• entry.metadata: Additional data (optional)
• entry.timestamp: Unix timestamp in milliseconds (optional, auto-generated)

Returns: void

trace.shutdown()

Gracefully shutdown telemetry and flush pending data.

Returns: Promise<void>

🖥️ CLI Usage

Basic Syntax

mcp-logger [options] <command...>

Options

• -k, --api-key <key>: API key (required)
  • Currently accepts any string value for testing
  • Sign up at Aware to get your API key for production use
• -s, --service-name <name>: Service name (optional)
• -e, --endpoint <url>: Custom OTLP endpoint (optional, default: https://aware.mcypher.com/v1/traces)
  • Send traces to any OTLP/HTTP compatible backend
  • Examples: Jaeger, Grafana Tempo, New Relic, Honeycomb, etc.
• -d, --debug: Enable debug logging (optional)
  • Shows detailed information about message processing and span creation

Examples

Wrap an npx command:

mcp-logger -k API_KEY -s filesystem npx -y @modelcontextprotocol/server-filesystem /path

Use with Claude Desktop:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": [
        "-y",
        "@awarecorp/mcp-logger",
        "-k",
        "YOUR_API_KEY",
        "-s",
        "my-server",
        "--",
        "npx",
        "-y",
        "your-mcp-server"
      ]
    }
  }
}

🏗️ How It Works

Request-Response Pairing

Creates one span per request-response pair for complete transaction context:

1. Request arrives → stored in pending map
2. Response arrives → matched by ID, single span created
3. Timeout (30s) → pending requests cleared
4. Notifications → handled as single-direction spans (request-only or response-only)

Message Type Handling

• Paired Spans: Request-response cycles with matching IDs (most common)
• Request-Only Spans: Client→server notifications (no response expected)
• Response-Only Spans: Server→client notifications (no matching request)

Tracked Methods

Configurable method filtering with exclusion list:

• Tracks: tools/call, tools/list, and other business-critical methods
• Excludes: notifications/initialized and other noisy protocol notifications
• Customizable via EXCLUDED_METHODS configuration

📊 Telemetry Data Structure

Each span includes:

• Request/response timestamps and payloads (with optional fields for notifications)
• Method name and parameters (separate fields for request/response)
• Tool names and arguments (for tools/call)
• Custom events and logs
• Enhanced error details with proper serialization
• Duration metrics
• CLI server information (command, args, env)

Span Attributes

All attributes use a flat structure optimized for Elasticsearch:

Core Attributes:

• Request attributes: mcp.request.* (id, method, params, timestamp)
• Response attributes: mcp.response.* (method, result, error, timestamp)
• Error handling: Proper serialization for Error objects, strings, and complex objects
• Metadata: source, transport, duration, tool information

Context Tracking:

• mcp.session.id: Unique session identifier
• mcp.conversation.id: Conversation/thread identifier
• mcp.user.id: User identifier (from params, headers, or environment)
• mcp.client.name: Client application name (e.g., 'Claude Desktop')
• mcp.client.version: Client version

Permission & Security:

• mcp.permission.level: Permission level (read/write/admin/elevated)

Resource Tracking:

• mcp.resource.type: Resource type (tool/file/prompt)
• mcp.resource.uri: Resource URI or identifier
• mcp.resource.access_count: Number of times resource accessed

📄 License

MIT © Aware Corp

🔗 Links

• Aware Corp
• npm Package
• Model Context Protocol