Cursor | Respan Docs

Set up Respan

Sign up — Create an account at platform.respan.ai
Create an API key — Generate one on the API keys page
Add credits or a provider key — Add credits on the Credits page or connect your own provider key on the Integrations page

Use AI

Add the Docs MCP to your AI coding tool to get help building with Respan. No API key needed.

1 {
2   "mcpServers": {
3     "respan-docs": {
4       "url": "https://mcp.respan.ai/mcp/docs"
5     }
6   }
7 }

Cursor is an AI-powered code editor with built-in agent capabilities. With Respan integration, you get hierarchical traces of every agent interaction including thinking blocks, file edits, shell commands, and MCP tool calls.

How It Works

Cursor provides hooks that fire during agent execution. Our integration captures these events in real-time and sends them to Respan as hierarchical traces.

The hook captures thinking blocks, file edits, shell commands, and MCP tool calls as child spans under a root agent span.

For details on trace structure and span types, see the Observability Data Model.

Prerequisites

Cursor IDE installed
Respan API key
Python 3.8+ with requests library

Installation

1. Set Environment Variables

Add these to your shell profile (.bashrc, .zshrc, or PowerShell $PROFILE):

$ export RESPAN_API_KEY="your-api-key"
$ export TRACE_TO_RESPAN="true"
$ 
$ # Optional: Enterprise endpoint (default: api.respan.ai)
$ # export RESPAN_BASE_URL="https://endpoint.respan.ai/api"
$ 
$ # Optional: Enable debug logging
$ # export CURSOR_RESPAN_DEBUG="true"

2. Download the Hook Script

Download the hook script to your Cursor hooks directory:

$ mkdir -p ~/.cursor/hooks
$ curl -o ~/.cursor/hooks/respan_hook.py \
>   https://raw.githubusercontent.com/respanai/respan-example-projects/main/python/dev-tools/cursor/respan_hook.py

3. Configure Cursor Hooks

Create ~/.cursor/hooks.json with the following configuration:

1 {
2   "version": 1,
3   "hooks": {
4     "beforeSubmitPrompt": [
5       { "command": "python ~/.cursor/hooks/respan_hook.py" }
6     ],
7     "afterAgentThought": [
8       { "command": "python ~/.cursor/hooks/respan_hook.py" }
9     ],
10     "afterAgentResponse": [
11       { "command": "python ~/.cursor/hooks/respan_hook.py" }
12     ],
13     "afterShellExecution": [
14       { "command": "python ~/.cursor/hooks/respan_hook.py" }
15     ],
16     "afterFileEdit": [
17       { "command": "python ~/.cursor/hooks/respan_hook.py" }
18     ],
19     "afterMCPExecution": [
20       { "command": "python ~/.cursor/hooks/respan_hook.py" }
21     ],
22     "stop": [
23       { "command": "python ~/.cursor/hooks/respan_hook.py" }
24     ]
25   }
26 }

4. Restart Cursor

Restart Cursor IDE to apply the hooks configuration.

Hooks Reference

Hook	Trigger	Data Captured
`beforeSubmitPrompt`	User sends prompt	User input, start time
`afterAgentThought`	Agent thinking	Thinking text, duration
`afterShellExecution`	Shell command completes	Command, output, duration
`afterFileEdit`	File edited	File path, edits
`afterMCPExecution`	MCP tool completes	Tool name, input, output, duration
`afterAgentResponse`	Agent responds	Response text (creates root span)
`stop`	Agent stops	Cleanup

Span Types

Span	`log_type`	Description
Root	`agent`	The complete agent turn
Thinking	`generation`	Agent reasoning blocks
Shell/File/MCP	`tool`	Tool invocations

Trace Fields

Field	Value	Description
`trace_unique_id`	`{conversation_id}_{generation_id}`	Unique per turn
`span_workflow_name`	`cursor_{conversation_id}`	Groups all turns
`thread_identifier`	`cursor_{conversation_id}`	Links turns in Threads view

Debugging

Check the log file for issues:

$ tail -f ~/.cursor/state/respan_hook.log

Common Issues

Issue	Solution
No traces appearing	Check `TRACE_TO_RESPAN=true` is set
API errors	Verify `RESPAN_API_KEY` is correct
Only root span	Ensure all hooks are configured in `hooks.json`
Missing thinking	Check `afterAgentThought` hook is active

Example Output

After setup, you’ll see traces in Respan with full hierarchy:

cursor_abc123_xyz789 (38.9s)
├── Thinking 1 (0.5s) - "Let me analyze the code..."
├── Thinking 2 (0.3s) - "I should update the function..."
├── Edit: utils.py (0.1s)
├── Shell: npm test (4.1s)
└── Thinking 3 (0.2s) - "Tests passed, done."

Source Code

The full source code is available on GitHub: Respan/respan-example-projects/cursor