Python SDK Installation

The mcpwatch package provides full Python support for MCPWatch. It works with any MCP server built on the official MCP Python SDK.

Requirements

• Python 3.10 or later
• An MCP server using mcp (the official Python SDK)

Install

pip install mcpwatch

Or with your preferred tool:

# uv
uv add mcpwatch

# poetry
poetry add mcpwatch

The SDK depends on httpx >= 0.28 and pydantic >= 2.10.

Basic setup

Instrument your MCP server with a single instrument() call:

import os
from mcp.server import Server
from mcpwatch import instrument

server = instrument(
    Server("my-server"),
    api_key=os.environ["MCPWATCH_API_KEY"],
    endpoint="https://api.mcpwatch.dev",
)

The instrument() function returns the same server instance with wrapped decorator methods. Your existing tool and resource registrations work exactly as before.

Configuration options

Option	Type	Default	Description
api_key	str	—	Your MCPWatch API key (required)
endpoint	str	"https://api.mcpwatch.dev"	MCPWatch ingestion endpoint
debug	bool	False	Enable debug logging
sample_rate	float	1.0	Event sampling rate from 0.0 to 1.0
max_batch_size	int	50	Max events per batch before flush
flush_interval	float	1.0	Time in seconds between automatic flushes
on_quota_warning	Callable[[QuotaInfo], None]	None	Callback when quota status is “warning” or “exceeded”

If api_key is empty, instrumentation is skipped entirely — the server runs without any wrapping.

Verify installation

Enable debug mode to confirm events are being captured and sent:

server = instrument(
    Server("my-server"),
    api_key=os.environ["MCPWATCH_API_KEY"],
    debug=True,
)

You’ll see log output from the mcpwatch logger confirming batch sends.

Next steps

• Usage Guide — Learn the SDK’s full feature set
• API Reference — Complete function and type documentation