get_cost_analytics

Instructions

Implementation Reference

• src/tools/analytics.tools.ts:410-441 (handler)

  The MCP tool handler (callback) for 'get_cost_analytics'. It calls service.analytics.getCostAnalytics, maps the response data points to {timestamp, total_cost, average_cost}, then formats and returns the result via formatGraphAnalytics.

  server.tool(
  	"get_cost_analytics",
  	"Get cost time-series data with summary.total_cost, summary.average_cost_per_request, and per-bucket total/avg cost. Use this for spend analysis and spike detection; use get_token_analytics when you need token volume instead of monetary cost.",
  	baseAnalyticsSchema,
  	async (params) => {
  		const analytics = await service.analytics.getCostAnalytics(
  			normalizeAnalyticsParams(params as Record<string, unknown>),
  		);
  		const dataPoints = analytics.data_points.map((point) => ({
  			timestamp: point.timestamp,
  			total_cost: point.total,
  			average_cost: point.avg,
  		}));
  		return {
  			content: [
  				{
  					type: "text",
  					text: JSON.stringify(
  						formatGraphAnalytics(
  							{
  								total_cost: analytics.summary.total,
  								average_cost_per_request: analytics.summary.avg,
  							},
  							dataPoints,
  						),
  						null,
  						2,
  					),
  				},
  			],
  		};
  	},

• src/tools/analytics.tools.ts:264-277 (helper)

  The formatGraphAnalytics helper function used by the handler to structure the response with summary, point_count, and data_points.

  function formatGraphAnalytics(
  	summary: Record<string, unknown>,
  	dataPoints: Record<string, unknown>[],
  ): {
  	summary: Record<string, unknown>;
  	point_count: number;
  	data_points: Record<string, unknown>[];
  } {
  	return {
  		summary,
  		point_count: dataPoints.length,
  		data_points: dataPoints,
  	};
  }

• src/services/analytics.service.ts:270-277 (handler)

  The actual service method getCostAnalytics that makes the HTTP GET request to '/analytics/graphs/cost' with the built analytics parameters.

  async getCostAnalytics(
  	params: CostAnalyticsParams,
  ): Promise<CostAnalyticsResponse> {
  	return this.get<CostAnalyticsResponse>(
  		"/analytics/graphs/cost",
  		this.buildAnalyticsParams(params),
  	);
  }

• src/services/analytics.service.ts:41-60 (schema)

  Type definitions for CostAnalyticsParams, CostAnalyticsResponse, CostDataPoint, and CostSummary - the input/output shapes for the cost analytics endpoint.

  // ==================== Cost Analytics Types ====================
  
  export interface CostDataPoint {
  	timestamp: string;
  	total: number;
  	avg: number;
  }
  
  export interface CostSummary {
  	total: number;
  	avg: number;
  }
  
  export interface CostAnalyticsResponse {
  	object: "analytics-graph";
  	data_points: CostDataPoint[];
  	summary: CostSummary;
  }
  
  export interface CostAnalyticsParams extends BaseAnalyticsParams {}

• src/tools/index.ts:30-39 (registration)

  The tool registration pipeline: registerAnalyticsTools is called from index.ts as part of the analytics domain (line 37). The tool name 'get_cost_analytics' is also listed in ENTERPRISE_GATED_TOOL_NAMES (line 111) for access control.

  const TOOL_DOMAIN_REGISTRARS = [
  	["users", registerUsersTools],
  	["workspaces", registerWorkspacesTools],
  	["configs", registerConfigsTools],
  	["keys", registerKeysTools],
  	["collections", registerCollectionsTools],
  	["prompts", registerPromptsTools],
  	["analytics", registerAnalyticsTools],
  	["guardrails", registerGuardrailsTools],
  	["limits", registerLimitsTools],