TypeScript API Reference

Full reference for all functions, classes, and types exported by @mcpwatch/sdk.

instrument()

The main SDK entry point. Wraps an MCP server to automatically capture events.

function instrument<T extends McpServerLike>(server: T, config: MCPWatchConfig): T

Parameters:

• server — An MCP server instance (e.g., McpServer from @modelcontextprotocol/sdk). Uses duck typing, so any object with compatible tool(), resource(), prompt(), connect(), and close() methods works.
• config — Configuration object (see MCPWatchConfig below)

Returns: The same server instance with wrapped methods. The return type matches the input type.

Example:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { instrument } from "@mcpwatch/sdk";

const server = instrument(
  new McpServer({ name: "my-server", version: "1.0.0" }),
  {
    apiKey: process.env.MCPWATCH_API_KEY ?? "",
    debug: true,
  }
);

---

MCPWatchClient

Low-level HTTP client for sending event batches to the MCPWatch ingestion API. Most users should use instrument() instead.

Constructor

new MCPWatchClient(config: MCPWatchConfig)

Methods

sendBatch(events)

Sends a batch of events to the ingestion API.

async sendBatch(events: McpWatchEvent[]): Promise<SendResult>

quotaStatus

Returns the most recent quota information from the last API response, or null if no response has been received.

get quotaStatus(): QuotaInfo | null

---

Types

MCPWatchConfig

interface MCPWatchConfig {
  apiKey: string;                             // Required: API key for authentication
  endpoint?: string;                          // Default: "https://api.mcpwatch.dev"
  debug?: boolean;                            // Default: false
  sampleRate?: number;                        // Default: 1.0 (range: 0.0–1.0)
  maxBatchSize?: number;                      // Default: 50
  flushInterval?: number;                     // Default: 1000 (ms)
  onQuotaWarning?: (info: QuotaInfo) => void; // Optional quota callback
}

EventType

type EventType =
  | "tool_call"
  | "resource_read"
  | "prompt_get"
  | "initialize"
  | "close"
  | "notification"
  | "error";

McpWatchEvent

interface McpWatchEvent {
  event_id: string;
  trace_id: string;
  span_id: string;
  parent_span_id: string | null;
  event_type: EventType;
  event_name: string;
  started_at: string;               // ISO 8601
  ended_at: string;                 // ISO 8601
  duration_ms: number;
  mcp_method: string;               // e.g., "tools/call", "resources/read"
  mcp_protocol_version: string;     // "2025-11-25"
  request_params: Record<string, unknown>;
  response_content: Record<string, unknown>;
  is_error: boolean;
  error_code: number | null;
  error_message: string | null;
  transport_type: string;           // "stdio", "sse", "streamable-http", "unknown"
  server_name: string;
  server_version: string;
  client_name: string;
  client_version: string;
  attributes: Record<string, string>;
  sdk_name: string;                 // "@mcpwatch/sdk"
  sdk_version: string;
}

QuotaInfo

interface QuotaInfo {
  limit: number;
  remaining: number;
  status: "ok" | "warning" | "exceeded" | "hard_limit";
  reset: string;                    // ISO 8601
}

SendResult

interface SendResult {
  response: IngestResponse | null;
  quotaInfo: QuotaInfo | null;
  retryAfter: number | null;
}

IngestResponse

interface IngestResponse {
  accepted: number;
  rejected: number;
  quota?: QuotaInfo;
}

---

Automatically captured operations

Operations captured by instrument():

Server Method	Event Type	MCP Method	Captured Data
tool() handler	tool_call	tools/call	Tool name, arguments, result, duration, errors
resource() handler	resource_read	resources/read	Resource name, params, response, duration
prompt() handler	prompt_get	prompts/get	Prompt name, params, response, duration
connect()	initialize	initialize	Transport type, server info, client info
close()	close	close	Server name
Notification methods	notification	varies	Notification type, params

Batching behavior

• Events queue in memory (max 1000 pending)
• Flush triggers: batch full (maxBatchSize), timer (flushInterval), or server.close()
• Failed sends retry once after 1 second, then drop
• HTTP timeout: 10 seconds per request
• Ingestion endpoint: POST /v1/events