cursor-otel
An MCP server that instruments Cursor AI agent interactions with OpenTelemetry traces and logs.
Each agent turn becomes an OTel span following the GenAI semantic conventions, with the user query and assistant response captured as span attributes. Logs emitted during a turn are correlated to the trace via context propagation.
Disclaimer
This is an experimental personal project. It is not affiliated with, endorsed by, or supported by Elastic, Cursor, or the OpenTelemetry project. Use at your own risk.
Tools
| Tool | Description |
|---|---|
start_turn | Begin a traced span for an agent turn. Returns a turn_id and conversation_id. |
end_turn | End the span for a turn. Accepts a response summary, tool count, and optional error. |
agent_log | Emit an OTel log record, optionally correlated to an active turn's trace. |
Setup
Prerequisites
An OpenTelemetry collector (or compatible backend) accepting OTLP/HTTP on http://localhost:4318. Override with the OTEL_EXPORTER_OTLP_ENDPOINT environment variable.
Install
git clone https://github.com/smith/cursor-otel.git
cd cursor-otel
npm install
Configure Cursor
Add to your .cursor/mcp.json:
{
"mcpServers": {
"cursor-otel": {
"command": "node",
"args": ["/absolute/path/to/cursor-otel/index.mjs"]
}
}
}
Agent rules
Add a Cursor rule (e.g. .cursor/rules/cursor-otel.mdc) to instruct the agent to call the tools on every turn:
## Agent OTel instrumentation
Every user interaction MUST be traced. Use the `cursor-otel` MCP tools.
### On each user query
1. Call `start_turn` with:
- `conversation_id`: reuse the value from the previous `start_turn` response
in this conversation. Omit on the first call (the server generates one).
- `user_message`: the user's query (first 500 chars).
- `model`: the model name if you know it.
2. Save the returned `turn_id` and `conversation_id`.
### After completing your response
Call `end_turn` with:
- `turn_id`: from `start_turn`.
- `response`: 1-2 sentence summary of what you did.
- `tool_count`: total number of tool calls you made this turn.
- `error`: set only if the turn failed.
### Logs
Use `agent_log` (with the `turn_id`) for notable events: errors, key decisions,
warnings. Don't log routine steps.
### Rules
- `start_turn` and `end_turn` are **mandatory** on every turn. No exceptions.
- Keep `start_turn` as the **first** tool call and `end_turn` as the **last**.
- These calls are fast and non-blocking — don't skip them to save time.