raindrop-mcp

Raindrop instrumentation for Python MCP servers. Works with the official SDK's mcp 1.x (FastMCP) and mcp 2.x (MCPServer), with the standalone fastmcp package (2.x and 3.x+), with a hand-wired low-level mcp.server.Server, and with any server built on them: wrap it once (or launch with raindrop-mcp) and every request the server answers lands in Raindrop as a tool span on an mcp_activity event: tool calls, prompts, resources, and the failures no handler sees (unknown tools, bad arguments, cancelled and dropped requests). Python twin of @raindrop-ai/mcp.

Install

pip install raindrop-mcp

Quick Start

No code changes: launch the server through raindrop-mcp with the write key in the environment.

RAINDROP_WRITE_KEY=... raindrop-mcp python server.py      # or: raindrop-mcp python -m my_server

RAINDROP_PROJECT_ID picks the project, RAINDROP_MCP_CAPTURE_CONTENT=false ships names, counts, errors and client identity but never arguments, results or intent, and RAINDROP_MCP_DISABLED=1 turns the launcher off without editing the command. Use either the launcher or wrap(), not both.

In code:

import os
from mcp.server.fastmcp import FastMCP  # mcp 2.x: from mcp.server.mcpserver import MCPServer
from raindrop_mcp import RaindropMcp

raindrop = RaindropMcp(api_key=os.environ.get("RAINDROP_API_KEY"))
mcp = raindrop.wrap(FastMCP("my-server"))

@mcp.tool()
def search(query: str) -> str:
    ...

mcp.run()

Omitting api_key disables shipping (a warning is emitted) but never crashes the server.

Third-party servers usually build their own FastMCP at import time. Wrap the class before importing them, or wrap the instance afterwards (tools already registered are instrumented too):

from mcp.server.fastmcp import FastMCP
from raindrop_mcp import RaindropMcp

RaindropMcp(api_key=...).wrap(FastMCP)   # every FastMCP built from now on
import some_mcp_server                   # noqa: E402
some_mcp_server.mcp.run()

The standalone fastmcp package works the same way:

from fastmcp import FastMCP
from raindrop_mcp import RaindropMcp

mcp = RaindropMcp(api_key=...).wrap(FastMCP("Demo"))

@mcp.tool
def add(a: int, b: int) -> int:
    return a + b

A hand-wired low-level server works too: raindrop.wrap(Server("my-server")) on an mcp.server.lowlevel.Server instance or the class.

What is recorded

Every JSON-RPC request the server answers is one call: tools/call (named by the tool), prompts/get <name>, resources/read <uri>, completion/complete, and so on, with mcp.method on the event and span. Failures carry mcp.error_type:

Lifecycle traffic never ships: initialize, server/discover, subscriptions/listen, ping and every */list, whether they succeed, fail or are still open when the connection closes.

An instrumented client that puts a W3C traceparent in params._meta has it recorded as mcp.traceparent. Credentials in URIs (user:pass@, query strings, fragments) are stripped from labels, arguments and error text.

Turn tracking

MCP has no turn boundary, so by default every tool advertises an optional _turn_id argument and every result ends with a _turn_id: <id> text block. The model copies it on its next call and omits it on a new prompt, so the calls of one prompt share one event (one trace, one tool span per call). The argument is removed before your tool runs. A tool that raises still echoes the id, so the model's next call stays on the same event.

If the client sends _meta["io.modelcontextprotocol/aiInvocation"].turnId (SEP-2817), that id is used and nothing is echoed.

turn_tracking=False leaves schemas and results untouched (this also disables intent); every call is then its own event.

Intent and client

Every tool also advertises an optional _intent argument: one sentence on what the user is trying to accomplish, which the model fills on the first call of a prompt. It is stripped before your tool runs, recorded as the mcp.intent property, and appended to the event input under a Session intent: line after MCP session started. Set intent=False to leave it out. It is free text the model wrote, so the key-based secret redaction does not apply to it; list _intent in redact_arguments to keep the field advertised but out of telemetry.

The MCP client that made the call (clientInfo, e.g. claude-code 2.1.0, Cursor, codex-mcp-client) is recorded as mcp.client_name / mcp.client_version on every span and event. It comes from the per-request _meta of 2026-era clients, or from the initialize handshake on older ones.

Options

call passed to the callables is a McpCallContext(tool_name, args, session_id, context), where context is the SDK's per-request Context.

Event properties

mcp.turn_id, mcp.tool (the latest call in the turn), mcp.method, mcp.is_error, mcp.error_type on failures, mcp.traceparent when the client sent one, mcp.client_name / mcp.client_version when the client identified itself, mcp.intent when the model filled _intent, mcp.session_id when the transport has one, plus anything from properties. Tool spans carry the arguments, the result text (or the error), mcp.turn_id, mcp.session_id, the client and the intent.

Known limitations

• Protocol-level calls (prompts, resources, handler-less failures) are recorded after the reply is sent and never wait for delivery; their caller identity comes from the request's HTTP headers (bearer token, session id), not the OAuth subject.
• On standalone fastmcp 2.x a tool that raises cannot echo the id (its ToolResult has no error form), so the model's next call starts a new event; 3.x+ echoes like the official SDK.
• _turn_id and _intent are added to the tool's JSON schema. A tool that declares either name itself keeps it: the field is neither advertised by this package nor stripped from the arguments for that tool, and a warning is emitted at registration since that tool then has no intent (or no turn grouping).
• Grouping depends on the model echoing _turn_id; clients that strip unknown result blocks start a new event per call.
• Delivery runs on the Raindrop SDK's background thread; await_delivery flushes before returning but cannot wait for a flush that thread already started.

Testing

pip install -e ".[dev]" && pytest

The suite runs unchanged against mcp<2 and mcp>=2.