@modelcontextprotocol/sdk

This guide covers how to instrument an MCP server built with @modelcontextprotocol/sdk. You will learn how to:

Install and configure the instrumentation
Track tool calls, resources, and prompts
Capture inputs and outputs

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

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.

server.ts

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 }) => {
  const results = await searchDatabase(query);
  return { content: [{ type: "text", text: JSON.stringify(results) }] };
});

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`)

Attribute	Description
`mcp.tool.result.content_count`	Number of content items returned
`mcp.tool.result.{i}.content_type`	Content type of each item
`mcp.tool.result.{i}.content`	Content value of each item
`mcp.prompt.result.description`	Prompt description
`mcp.prompt.result.message_count`	Number of messages returned
`mcp.prompt.result.{i}.role`	Message role
`mcp.prompt.result.{i}.content`	Message content

Getting Started

Monocle Studio

Frameworks

Features

Integrations

Other

@modelcontextprotocol/sdk

Installation

Usage

Configuration

Spans

Request spans

Notification spans

Outgoing notification spans

Error spans

SDK-specific attributes

Input attributes (when `recordInputs: true`)

Output attributes (when `recordOutputs: true`)

​Installation

​Usage

​Configuration

​Spans

​Request spans

​Notification spans

​Outgoing notification spans

​Error spans

​SDK-specific attributes

​Input attributes (when recordInputs: true)

​Output attributes (when recordOutputs: true)

Installation

Usage

Configuration

Spans

Request spans

Notification spans

Outgoing notification spans

Error spans

SDK-specific attributes

Input attributes (when `recordInputs: true`)

Output attributes (when `recordOutputs: true`)