Documentation

Quick Start

Get MCPWatch running on your MCP server in under 2 minutes.

1. Create an account

2. Install the agent

npm install @mcpwatch/agent

3. Initialize in your MCP server

import MCPWatch from '@mcpwatch/agent';

const monitor = new MCPWatch({
  token: process.env.MCPWATCH_TOKEN,
  // Optional: custom endpoint for self-hosted
  // endpoint: 'https://your-instance.com'
});

// Track requests
app.use((req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    monitor.trackRequest(Date.now() - start);
  });
  next();
});

// Track errors
app.use((err, req, res, next) => {
  monitor.trackError(err);
  next(err);
});

4. Set your environment variable

# .env
MCPWATCH_TOKEN=mw_your_agent_token_here

Find your agent token in the dashboard under Server Settings.

Agent API

new MCPWatch(options)

Creates a new MCPWatch monitoring instance.

Option	Type	Description
token	string	Your MCPWatch agent token (required)
endpoint	string	API endpoint (default: https://mcpwatch.vercel.app)
interval	number	Heartbeat interval in ms (default: 60000)

monitor.trackRequest(durationMs, tokens?)

Track an API request. Call after each request completes. Optionally pass token count for cost tracking.

monitor.trackError(error)

Report an error. Automatically captures stack trace and sends to MCPWatch for logging.

monitor.trackTokens(inputTokens, outputTokens, provider?)

Track token usage for cost calculation. Provider defaults to "default" pricing. Supported: openai-gpt4, openai-gpt4o, anthropic-claude-3-sonnet, etc.

monitor.trackCustomMetric(name, value, aggregation?)

Track a custom business metric. Aggregation controls how values are combined at each heartbeat interval.

Option	Type	Description
name	string	Metric name (e.g., 'active_users', 'queue_depth')
value	number	Metric value
aggregation	string	'sum' (default), 'avg', 'max', or 'last'

REST API

All API endpoints accept and return JSON. Authenticate with your agent token in the Authorization header.

POST/api/metrics

Submit server metrics (called by agent automatically)

POST/api/errors

Report an error with stack trace and context

GET/api/servers

List all your monitored servers

GET/api/status/:server-token

Public status endpoint for a specific server

FAQ

Does the agent add latency to my server?

No. The agent runs asynchronously and batches metrics. It adds less than 1ms of overhead per request. Heartbeats are sent in the background every 60 seconds.

How much bandwidth does the agent use?

Each heartbeat is approximately 200 bytes. At the default 60-second interval, that is roughly 8KB per hour or 200KB per day.

Can I self-host MCPWatch?

Not yet, but it is on the roadmap. The agent supports custom endpoints, so you can point it to your own instance when available.