MCP Tools Reference

Spotlight provides four MCP tools that allow AI coding assistants to query your application’s runtime data.

Tool Overview

Tool	Purpose	Returns
search_errors	Find runtime errors	Errors with stack traces
search_logs	Query application logs	Log entries with context
search_traces	List performance traces	Trace summaries
get_traces	Get trace details	Full span tree and timing

Common Filter Parameters

All search tools support these filter options:

timeWindow

Look back a specified number of seconds from now.

• Type: Number (seconds)
• Examples:
  • 60 - Last minute
  • 300 - Last 5 minutes
  • 3600 - Last hour

Example:

{
  "filters": {
    "timeWindow": 300
  }
}

filename

Search for events related to a specific file (exact match, case-sensitive).

• Type: String
• Examples:
  • "auth.js"
  • "Button.tsx"
  • "api/users.ts"

Example:

{
  "filters": {
    "filename": "auth.js"
  }
}

limit and offset

Paginate through results.

• Type: Number
• Examples:
  • limit: 10 - Return first 10 results
  • limit: 20, offset: 10 - Skip first 10, return next 20

Example:

{
  "filters": {
    "limit": 10,
    "offset": 0
  }
}

---

search_errors

Search for runtime errors, exceptions, and crashes captured by Spotlight.

Purpose

Find and analyze application errors with full context:

• Complete stack traces with file and line numbers
• Error messages and types (TypeError, ReferenceError, etc.)
• Request/response context for API failures
• Browser/device information when available

When to Use

Use this tool when:

• User reports “error”, “broken”, “not working”, “crash”, or “bug”
• Investigating unexpected application behavior
• Verifying no regressions after code changes
• Debugging errors in specific files

Parameters

{
  filters: {
    timeWindow?: number,      // Seconds to look back
    filename?: string,        // Exact filename in stack trace
    limit?: number,           // Max results
    offset?: number          // Skip first N results
  }
}

Usage Examples

Get Recent Errors

{
  "filters": {
    "timeWindow": 60
  }
}

Returns errors from the last minute.

Find Errors in Specific File

{
  "filters": {
    "filename": "auth.tsx"
  }
}

Returns all errors with auth.tsx in the stack trace.

Paginated Error Search

{
  "filters": {
    "limit": 10,
    "offset": 0
  }
}

Returns first 10 errors.

Response Format

Each error includes:

• Error Message: The exception message
• Error Type: Exception class (e.g., TypeError, ReferenceError)
• Stack Trace: Full stack with file:line:column
• Timestamp: When the error occurred
• Context: Additional information (request data, user info, etc.)

Example AI Prompts

• “Are there any errors in my app?”
• “Show me errors from the last 5 minutes”
• “Find errors in the authentication module”
• “What’s causing the TypeError in user.js?“

---

search_logs

Search application logs to understand behavior, debug issues, and trace execution flow.

Purpose

Query logs to see:

• Application execution flow and behavior
• Debug messages and timing information
• API request/response logs with context
• Database query logs with performance metrics

When to Use

Best for:

• Understanding how the application works
• User mentions “logs”, “debugging”, or “trace”
• Investigating what the app is doing internally
• Performance investigation and timing analysis

Note

For error diagnostics with stack traces, use search_errors instead.

Parameters

{
  filters: {
    timeWindow?: number,      // Seconds to look back
    filename?: string,        // Exact filename generating logs
    limit?: number,           // Max results
    offset?: number          // Skip first N results
  }
}

Log Levels

• INFO: General application flow and significant events
• WARN: Potential issues that don’t break functionality
• DEBUG: Detailed execution information for troubleshooting

Note

ERROR level logs are available, but search_errors provides more detailed error context including stack traces.

Usage Examples

Check Recent Activity

{
  "filters": {
    "timeWindow": 300
  }
}

Returns logs from the last 5 minutes.

Find Logs from Specific File

{
  "filters": {
    "filename": "database.ts"
  }
}

Returns logs generated by database.ts.

Get Latest Log Entries

{
  "filters": {
    "limit": 20,
    "offset": 0
  }
}

Returns 20 most recent log entries.

Response Format

Each log entry includes:

• Level: Log severity (info, warn, debug)
• Message: The log message
• Timestamp: When it was logged
• Attributes: Custom structured data (user_id, request_id, duration, etc.)
• Source: File and line number (when available)

Example AI Prompts

• “Show me recent logs”
• “What’s happening in the authentication flow?”
• “Show me database query logs”
• “How long are API requests taking?“

---

search_traces

List recent performance traces with summary information.

Purpose

Get an overview of recent application activity:

• Trace IDs and root transaction names
• Total duration and span counts
• Error counts per trace
• Timestamps for timeline analysis

When to Use

Perfect for:

• Investigating performance issues or slow requests
• User mentions “traces”, “performance”, or “slow”
• Finding specific transactions or requests
• Getting an overview of recent activity

Parameters

{
  filters: {
    timeWindow?: number,      // Seconds to look back
    filename?: string,        // Exact filename in trace spans
    limit?: number,           // Max results
    offset?: number          // Skip first N results
  }
}

Usage Examples

Get Recent Traces

{
  "filters": {
    "timeWindow": 300
  }
}

Returns traces from the last 5 minutes.

Find Most Recent Traces

{
  "filters": {
    "limit": 10,
    "offset": 0
  }
}

Returns 10 most recent traces.

Find Traces Involving Specific File

{
  "filters": {
    "filename": "api.ts"
  }
}

Returns traces with spans from api.ts.

Response Format

Each trace summary includes:

• Trace ID: Unique identifier (first 8 chars shown)
• Transaction Name: Root operation (e.g., “GET /api/users/:id”)
• Duration: Total time in milliseconds
• Span Count: Number of operations in the trace
• Error Count: Number of errors in this trace
• Timestamp: When the trace started

Next Step

After finding a trace of interest, use get_traces with the trace ID to see detailed timing breakdown.

Example AI Prompts

• “Show me recent traces”
• “What requests happened in the last minute?”
• “Find slow transactions”
• “Show me traces with errors”

---

get_traces

Get complete span tree and timing breakdown for a specific trace.

Purpose

Deep-dive into a specific trace to see:

• Hierarchical span tree with parent-child relationships
• Individual operation durations for each span
• Database queries, API calls, and render timings
• Error details within the trace timeline

When to Use

Use this after:

• Finding a trace ID from search_traces
• Investigating a specific slow request or transaction
• Understanding detailed execution flow
• Finding performance bottlenecks in a trace

Parameters

{
  traceId: string  // Full 32-char hex or first 8 chars
}

The trace ID can be:

• First 8 characters: "71a8c5e4"
• Full 32 characters: "71a8c5e41ae1044dee67f50a07538fe7"

Usage Examples

Using Short Trace ID

{
  "traceId": "71a8c5e4"
}

Using Full Trace ID

{
  "traceId": "71a8c5e41ae1044dee67f50a07538fe7"
}

Response Format

Returns a hierarchical span tree showing:

• Span ID: Unique identifier for each operation
• Operation: Description of what the span does
• Duration: Time in milliseconds
• Start Time: When the operation started (relative to trace start)
• Parent/Child Relationships: How operations nest
• Status: ok, error, etc.
• Tags/Data: Additional context (SQL queries, HTTP methods, etc.)

Example structure:

Transaction: GET /api/users/123 (245ms)
├─ Database Query: SELECT * FROM users (45ms)
├─ HTTP Request: GET external-api.com (180ms)
│  └─ DNS Lookup (5ms)
└─ Process Response (20ms)
   └─ Error: Cannot read property 'id'

Example AI Prompts

• “Show me details for trace 71a8c5e4”
• “Analyze trace abc12345 for performance issues”
• “Why is trace xyz taking so long?”
• “Show me the span tree for this slow request”

---

Workflow Patterns

Error Investigation

1. Search for errors: search_errors
2. If error mentions a trace: Get trace details with get_traces
3. Check related logs: search_logs with filename from error

Performance Analysis

1. List recent traces: search_traces
2. Identify slow traces: Look at duration in summary
3. Deep dive: get_traces with trace ID
4. Check logs: search_logs for timing details

Understanding Application Behavior

1. Check logs: search_logs for recent activity
2. Look for errors: search_errors for issues
3. Examine traces: search_traces for request flow

Best Practices

Time Windows

• Use 60s (1 minute) for recent activity
• Use 300s (5 minutes) for broader investigation
• Use 3600s (1 hour) for historical analysis

Pagination

• Start with limit: 10 to avoid overwhelming output
• Use offset to load more if needed
• For specific issues, filter by filename instead of paginating

Combining Filters

You can only use one filter type at a time:

• Either timeWindow
• Or filename
• Or limit/offset

Choose the most specific filter for your use case.

Following Trace IDs

Traces often reference related data:

1. Errors include trace IDs → use get_traces
2. Logs include trace IDs → use get_traces
3. Trace spans reference files → use search_logs or search_errors with filename

Next Steps

• See MCP workflows - Common debugging patterns
• MCP server setup - Getting started guide
• CLI reference - Command-line tools