@modelcontextprotocol/sdk

For the full list of required span attributes and what powers the MCP dashboard, see the MCP feature page.

Installation

npm install @monocle.sh/instrumentation-mcp

Peer dependency: @modelcontextprotocol/sdk >= 1.0.0

With the AdonisJS agent

Install this package explicitly and use the direct import shown below. Initialize the agent before loading your MCP server module, then call instrumentMcpServer() before connecting the transport. No integrations entry is needed.

Usage

Call instrumentMcpServer() on your server instance before connecting a transport. This wraps the server's internal handlers to create spans for every incoming request, notification, and outgoing message.

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

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

instrumentMcpServer(server)

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

const transport = new StdioServerTransport()
await server.connect(transport)

Configuration

instrumentMcpServer(server, {
  // Capture tool/prompt arguments in span attributes (default: false)
  recordInputs: true,

  // Capture tool results and prompt messages in span attributes (default: false)
  recordOutputs: true,

  // Override auto-detected server name/version
  serverName: 'my-server',
  serverVersion: '1.0.0',
})

Spans

The instrumentation creates spans for three categories of MCP activity.

Request spans

A SERVER span is created for every incoming JSON-RPC request (tools/call, resources/read, prompts/get, initialize, etc.).

The span name includes the target when available: tools/call search, resources/read config://app, prompts/get weather.

Notification spans

A SERVER span is created for incoming notifications (e.g., notifications/initialized, resources/changed).

Outgoing notification spans

A CLIENT span is created for outgoing notifications sent by the server (e.g., resources/changed).

Error spans

Transport errors produce an INTERNAL span named mcp.transport.error with the exception recorded. JSON-RPC errors set rpc.jsonrpc.error_code and rpc.jsonrpc.error_message on the request span.

SDK-specific attributes

In addition to the standard MCP attributes, this instrumentation emits these extra attributes when recording is enabled.

Input attributes (when recordInputs: true)

Tool arguments are captured as mcp.request.argument.{key} (JSON-stringified per key).

Output attributes (when recordOutputs: true)