MCP SDK

​

Setup

pnpm add braintrust @modelcontextprotocol/server zod

npm install braintrust @modelcontextprotocol/server zod

BRAINTRUST_API_KEY=<your-braintrust-api-key>

​

Auto-instrumentation

import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import { initLogger } from "braintrust";
import { z } from "zod";

initLogger({ projectName: "my-mcp-server" }); // Replace with your project name

const server = new McpServer({ name: "weather", version: "1.0.0" });

server.registerTool(
  "get_weather",
  {
    description: "Get the current weather for a city",
    inputSchema: z.object({ city: z.string() }),
  },
  async ({ city }) => ({
    content: [{ type: "text", text: `Sunny in ${city}` }],
  }),
);

await server.connect(new StdioServerTransport());

node --env-file=.env --import braintrust/hook.mjs mcp-server.js

BRAINTRUST_DISABLE_INSTRUMENTATION=mcp node --env-file=.env --import braintrust/hook.mjs mcp-server.js

​

Manual instrumentation

import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import { initLogger, wrapMCPServer } from "braintrust";

initLogger({ projectName: "my-mcp-server" }); // Replace with your project name

const server = wrapMCPServer(new McpServer({ name: "weather", version: "1.0.0" }));

// Register tools, prompts, and resources on the server

await server.connect(new StdioServerTransport());

​

Omit arguments and results

import { configureInstrumentation } from "braintrust/instrumentation";

configureInstrumentation({
  integrations: {
    mcp: { captureContent: false },
  },
});

node --env-file=.env --import ./configure.mjs --import braintrust/hook.mjs mcp-server.js

​

Link requests to the client’s trace

pnpm add @modelcontextprotocol/client

npm install @modelcontextprotocol/client

import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
import { initLogger, injectTraceContext, traced } from "braintrust";

const logger = initLogger({ projectName: "my-mcp-server" }); // Replace with your project name

const client = new Client({ name: "weather-client", version: "1.0.0" });
await client.connect(
  new StdioClientTransport({
    command: "node",
    args: ["--env-file=.env", "--import", "braintrust/hook.mjs", "mcp-server.js"],
  }),
);

await traced(
  async () => {
    await client.callTool({
      name: "get_weather",
      arguments: { city: "Paris" },
      _meta: injectTraceContext(),
    });
  },
  { name: "ask-weather" },
);

await logger.flush();
await client.close();

​

What Braintrust traces

• Tool call spans (tools/call <tool>), recorded as tool spans, with gen_ai.tool.name in metadata. With content capture on, they also record the tool arguments as input and the tool result as output.
• Prompt request spans (prompts/get <prompt>), with gen_ai.prompt.name in metadata. With content capture on, they also record the prompt arguments as input and the prompt result as output.
• Spans for other requests, named after the MCP method, such as initialize, tools/list, and resources/read. With content capture on, resources/read spans also record the resource URI as input and the resource contents as output.
• Notification spans, named after the MCP method, such as notifications/initialized, notifications/progress, and notifications/message. mcp.notification.direction is incoming for notifications the server receives and outgoing for notifications it sends, and an outgoing notification sent for a request nests under that request’s span.
• Progress and logging notification metadata, with progress values, level, and logger. With content capture on, notification spans also record the notification parameters.
• Request metadata, including mcp.method.name, jsonrpc.request.id, mcp.session.id, mcp.protocol.version, mcp.resource.uri, and the transport protocol.
• Client and server identity from the initialize exchange (mcp.client.name, mcp.client.version, mcp.server.name, and mcp.server.version, plus title when reported) on spans for the rest of the session. On HTTP transports without a session ID, later spans record only the identity and protocol version that each request and response report.
• Errors, including tool results marked as errors, JSON-RPC error responses, handler exceptions, and connections that close before the response is sent, with the error category in error.type. Spans for JSON-RPC error responses record the error code in rpc.response.status_code. Responses that reject the client’s request, such as method not found or invalid params, record the code without marking the span as an error.
• Cancelled requests, marked with mcp.cancelled.

​

Resources

• Model Context Protocol TypeScript SDK
• MCP server SDK on npm
• MCP client SDK on npm
• Braintrust package on npm