Prepare the server locally
Run this once before adding it to Claude Code.
git clone https://github.com/smith/cursor-otel.git
cd cursor-otel
npm installRegister it in Claude Code
claude mcp add cursor-otel -- node /absolute/path/to/cursor-otel/index.mjsReplace any placeholder paths in the command with the real path on your machine.
Make your agent remember this setup
cursor-otel's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session.
npx conare@latestFree · one command · indexes the sessions already on disk. Set up in the browser instead →
What it does
- Instruments Cursor AI agent turns with OpenTelemetry traces
- Captures user queries and assistant responses as span attributes
- Correlates logs to agent turns via context propagation
- Follows GenAI semantic conventions for telemetry spans
Tools 3
start_turnBegin a traced span for an agent turn.end_turnEnd the span for a turn.agent_logEmit an OTel log record, optionally correlated to an active turn's trace.Environment Variables
OTEL_EXPORTER_OTLP_ENDPOINTThe OTLP/HTTP endpoint for the OpenTelemetry collector (defaults to http://localhost:4318)Try it
Original README from smith/cursor-otel
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.