@monocle.sh/instrumentation-mcp

OpenTelemetry instrumentation for MCP (Model Context Protocol) servers. Automatically traces JSON-RPC requests, responses, notifications, and handler errors with zero configuration.

Installation

Preferred — via the AdonisJS agent (already includes this package):

npm install @monocle.sh/adonisjs-agent

import { instrumentMcpServer } from '@monocle.sh/adonisjs-agent/mcp'

Standalone:

npm install @monocle.sh/instrumentation-mcp

import { instrumentMcpServer } from '@monocle.sh/instrumentation-mcp'

Usage

Call instrumentMcpServer once on your MCP server instance before connecting transports:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { instrumentMcpServer } from '@monocle.sh/instrumentation-mcp'

const server = new McpServer({ name: 'my-server', version: '1.0.0' })

instrumentMcpServer(server, {
  recordInputs: true,
  recordOutputs: true,
})

server.tool('search', { query: z.string() }, async ({ query }) => {
  return { content: [{ type: 'text', text: `Results for ${query}` }] }
})

// Connect transport as usual — instrumentation hooks in automatically
const transport = new StdioServerTransport()
await server.connect(transport)

The function is idempotent — calling it twice on the same server returns the same instance.

Options

| Option | Type | Default | Description | | --------------- | --------- | ----------- | --------------------------------------------------------------- | | recordInputs | boolean | false | Capture tool/prompt arguments as span attributes | | recordOutputs | boolean | false | Capture tool results and prompt messages as span attributes | | serverName | string | auto-detect | Server name added to all spans (auto-detected from McpServer) | | serverVersion | string | auto-detect | Server version added to all spans |

Span Attributes

Core

| Attribute | Description | Example | | ----------------- | -------------------- | ---------------------- | | mcp.method.name | JSON-RPC method name | tools/call | | mcp.request.id | JSON-RPC request ID | 1 | | mcp.session.id | Transport session ID | abc-123 | | mcp.transport | Transport class name | StdioServerTransport |

Client & Server

| Attribute | Description | Example | | ---------------------- | -------------------------------- | ------------- | | mcp.client.name | Client name from initialize | Claude Code | | mcp.client.version | Client version from initialize | 1.0.0 | | mcp.server.name | Server name | my-server | | mcp.server.version | Server version | 2.0.0 | | mcp.protocol.version | MCP protocol version | 2025-06-18 |

Method-Specific

| Attribute | Description | Example | | ------------------ | ------------------------------ | ------------------- | | mcp.tool.name | Tool name for tools/call | search | | mcp.resource.uri | Resource URI for resources/* | file:///readme.md | | mcp.prompt.name | Prompt name for prompts/get | code-review |

Tool Result (when recordOutputs: true)

| Attribute | Description | Example | | ------------------------------- | ------------------------------ | ------- | | mcp.tool.result.is_error | Whether tool returned an error | true | | mcp.tool.result.content_count | Number of content items | 2 | | mcp.tool.result.content | Text content (single item) | hello | | mcp.tool.result.{i}.content | Text content (multiple items) | hello |

Prompt Result (when recordOutputs: true)

| Attribute | Description | Example | | ----------------------------------- | ------------------------ | ----------- | | mcp.prompt.result.description | Prompt description | Review... | | mcp.prompt.result.message_count | Number of messages | 2 | | mcp.prompt.result.message_role | Message role (single) | assistant | | mcp.prompt.result.message_content | Message content (single) | Hello |

Request Arguments (when recordInputs: true)

| Attribute | Description | Example | | ----------------------------- | ------------------------- | --------- | | mcp.request.argument.{name} | Serialized argument value | "hello" |

JSON-RPC Errors

| Attribute | Description | Example | | --------------------------- | ---------------------- | ---------------- | | rpc.jsonrpc.error_code | JSON-RPC error code | -32603 | | rpc.jsonrpc.error_message | JSON-RPC error message | Internal error |

What Gets Traced

• Incoming requests — tools/call, resources/read, prompts/get, etc. create SERVER spans that remain open until the response is sent
• Outgoing responses — complete the corresponding request span with result attributes
• Incoming notifications — notifications/initialized, etc. create short-lived SERVER spans
• Outgoing notifications — notifications/tools/list_changed, etc. create CLIENT spans
• Transport errors — connection errors create INTERNAL spans with ERROR status
• Handler errors — exceptions in tool/resource/prompt handlers are recorded on the active span
• Transport close — cancels any pending request spans with ERROR/cancelled status