@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 \
  -- 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 (SDK mode)
• 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

Data Format

Flat key-value structure optimized for Elasticsearch/OpenSearch:

Discriminator & Type:

• ingest.type: Always "mcp" — backend event type discriminator
• mcp.type: "paired" | "request" | "response" — span type
• mcp.method: JSON-RPC method name (e.g. "tools/call")
• mcp.transport: "stdio" | "sse"

Request/Response:

• mcp.request.id / mcp.response.id: JSON-RPC message IDs
• mcp.request.method / mcp.response.method: Method names
• mcp.request.params / mcp.response.result: Payloads (JSON string)
• mcp.request.timestamp / mcp.response.timestamp: Unix timestamps
• mcp.duration_ms: Request duration (paired spans only)

Tool (tools/call):

• mcp.tool.name: Tool name
• mcp.tool.arguments: Tool arguments (JSON string)

Error:

• mcp.error: Boolean flag
• mcp.error.code: Error code
• mcp.error.message: Error message

Context:

• mcp.session.id: Session identifier
• mcp.conversation.id: Conversation identifier
• mcp.user.id: User identifier
• mcp.client.name / mcp.client.version: Client info (e.g. "Claude Desktop")
• mcp.sdk.name / mcp.sdk.version: MCP SDK/framework info

Other:

• mcp.cli: CLI server info (command, args, env) as JSON string
• mcp.events: Custom log entries (JSON array, SDK mode)
• mcp.headers: Transport headers (SSE only)
• mcp.resource.type / mcp.resource.uri: Resource tracking
• mcp.permission.level: Permission level
• mcp.cost: Estimated cost

🔧 SDK API

trace(server, options)

Enable automatic instrumentation on an MCP server.

Parameters:

• server: MCP Server instance
• options.apiKey: API key for authentication (required)
• options.serviceName: Service identifier (optional, auto-generated if omitted)
• options.endpoint: Custom OTLP endpoint (optional)

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)
• -e, --endpoint <url>: Custom OTLP endpoint (optional)

Examples

Wrap an npx command:

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

Use with Claude Desktop:

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

🏗️ How It Works

Message Type Handling

• Paired Spans (mcp.type: "paired"): Request-response cycles with matching IDs. Duration automatically calculated.
• Request Spans (mcp.type: "request"): Timed-out requests (30s) with no matching response.
• Response Spans (mcp.type: "response"): Server→client notifications or unmatched responses.

Request-Response Pairing

1. Request arrives → stored in pending map with timestamp
2. Response arrives → matched by JSON-RPC ID, paired span created with duration
3. Timeout (30s) → request span created for unmatched requests
4. Notifications → handled as response spans (no ID to match)

Tracked Methods

Configurable method filtering with exclusion list:

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

📄 License

MIT © Aware Corp

🔗 Links

• Aware Corp
• npm Package
• Model Context Protocol