Manual

Documentation

NetTrace AI captures HTTP requests from your browser and surfaces them in your IDE so you can debug faster. Free features work with no account. Premium unlocks real-time IDE streaming, AI language-model tools, and device management.

01 · Getting Started

NetTrace AI is installed from official browser stores — the same way you add any other extension. Free capture features require no account.

Chrome Web Store

  1. Open the NetTrace AI listing on the Chrome Web Store.
  2. Click Add to Chrome and confirm the permissions prompt.
  3. Optional: click the puzzle-piece icon in Chrome's toolbar and pin NetTrace AI for quick access.

Firefox Add-ons

  1. Open the NetTrace AI listing on Firefox Add-ons.
  2. Click Add to Firefox and confirm.
  3. Optional: pin the extension from the extensions menu for one-click access.

First-Time Consent

The first time you click the NetTrace icon after installing, a consent banner appears. Choose the capture scope that fits your workflow:

  • Current site only — captures requests from the active tab's domain.
  • All sites — captures every request on every tab.
  • Localhost only — limits capture to localhost and 127.0.0.1.
  • Allowlist — captures only on domains you specify.

You can change the scope at any time from the extension's Settings panel.

02 · Browser Extension Guide

A tour of the extension popup — from opening it to copying AI-ready markdown.

Opening the Popup

Click the NetTrace AI icon in your browser's toolbar. The popup shows a live list of captured HTTP requests.

Request List

Requests are listed newest first. Each row displays the HTTP method, URL, status code, and response timing at a glance.

Expanding a Request

Click any request row to expand its detail view. The detail panel opens inline below the row. Click the X button or click the row again to collapse it.

Detail Tabs

The expanded view includes four tabs with complete request and response data:

  • Headers — request and response headers (sensitive values are masked based on your privacy settings).
  • Payload — the request body (POST/PUT/PATCH data, JSON payloads, form data).
  • Response — the response body, formatted when JSON is detected.
  • Timing — duration breakdown showing total time and server timing headers when available.

Filtering

Use the search bar at the top of the request list to filter by URL or method. Quick-filter buttons let you narrow by status category:

  • Success — 2xx responses
  • Redirect — 3xx responses
  • Client Error — 4xx responses
  • Server Error — 5xx responses

Copy to Clipboard

Select one or more requests using the checkboxes on each row, then click the Copy button. The selected requests are exported as AI-ready markdown with sensitive fields automatically redacted based on your masking settings. Paste directly into ChatGPT, Claude, Cursor chat, or bug reports.

Resizable Popup

Drag the bottom edge of the popup to resize it. Your preferred height is saved automatically and restored the next time you open the extension.

03 · Extension Settings

Open Settings from the gear icon inside the extension popup. Every option is described below.

Capture

  • Enable / Disable capture — master toggle to start or stop recording network requests.
  • Max requests — maximum number of requests to keep in memory. Default: 500. Older requests are dropped when the limit is reached.
  • Max body size — cap on request/response body size stored per entry. Default: 50 KB. Larger bodies are truncated.

Headers

  • Capture request headers — toggle whether request headers are stored.
  • Capture response headers — toggle whether response headers are stored.

Bodies

  • Capture request bodies — toggle to store POST / PUT / PATCH payloads.
  • Capture response bodies — toggle to store response content.

Capture Types

Toggle which resource types are captured. Each type can be independently enabled or disabled:

  • XHR — XMLHttpRequest calls
  • Fetch — Fetch API calls
  • Document — HTML document loads
  • WebSocket — WebSocket connections
  • Script — JavaScript files
  • Stylesheet — CSS files
  • Image — image resources
  • Font — font files
  • Other — any other request type

Privacy Scope

Controls which sites are captured. Choose one:

  • Current site — only the active tab's domain.
  • All sites — every domain on every tab.
  • Localhost — only localhost / 127.0.0.1.
  • Allowlist — only domains you specify.
  • Paused — capture is fully paused.

Masking

Automatically redact sensitive data before it appears in copied output or is sent to your IDE. Each category can be toggled independently:

  • Authorization headers
  • Bearer tokens
  • API keys
  • Cookies
  • Passwords
  • Custom regex — add your own patterns for project-specific secrets.

Display

  • Full URL vs. base only — show the complete URL or just the path without query parameters.
  • Timing — show or hide response time on each row.
  • Cookies — show or hide cookie headers in the detail view.
  • Auth headers — show or hide authorization headers in the detail view.

Auto-Send to IDE (Premium)

When enabled, failed requests (4xx and 5xx) are automatically streamed to your IDE companion in real time. No manual selection required — errors appear in your IDE as they happen.

04 · Premium Features

Premium unlocks three capabilities on top of the free extension: IDE companion integration, device dashboard, and auto-send. Every new account receives a 30-day free trial — no credit card required to start.

Connecting Your Account

  1. Sign in at nettrace.ai and open your dashboard.
  2. Navigate to Extension Setup to generate a device token.
  3. In your IDE, run the NetTrace: Connect Account command and paste the device token when prompted.

Send to IDE Button

In the browser extension, select one or more requests using the checkboxes, then click the IDE button. The selected requests are sent directly to your running VS Code or Cursor instance — no copy/paste required.

Auto-Send

Enable Auto-send to IDE in the extension settings. When active, every failed request (4xx/5xx) is automatically streamed to your IDE companion as it happens — no manual selection needed.

05 · IDE Companion Extension

The NetTrace IDE Companion works in both Cursor and VS Code. Install it from the VS Code Marketplace — search for NetTrace AI or use the direct link. The setup differs slightly between editors, so follow the guide for yours below.

Setup for Cursor

Cursor uses MCP (Model Context Protocol) for external tool integrations. After installing the extension, you need to configure the MCP server so Cursor's AI can call NetTrace tools automatically.

  1. Install the extension — install NetTrace AI — IDE Companion from the VS Code Marketplace, or search for NetTrace AI in Cursor's Extensions panel.
  2. Connect your account — open the Command Palette (Ctrl+Shift+P), run NetTrace: Connect Account, and paste your device token from nettrace.ai/dashboard/extension-setup.
  3. Verify the receiver — the status bar at the bottom should show NetTrace: Listening or NetTrace: Connected (N). If it shows "Stopped", run NetTrace: Start Local Receiver.
  4. Configure MCP — run NetTrace: Show MCP Setup from the Command Palette. Cursor will offer to auto-write the config. If it doesn't, create a file at .cursor/mcp.json in your workspace root:
    {
  "mcpServers": {
    "nettrace": {
      "command": "node",
      "args": ["<path-to-extension>/dist/mcp-server.js"],
      "env": {
        "NETTRACE_TOKEN": "<your-device-token>"
      }
    }
  }
}

    Replace <path-to-extension> with your installed extension path (shown by Show MCP Setup) and <your-device-token> with your token.

  5. Reload Cursor — run Developer: Reload Window from the Command Palette.
  6. Send a request — browse any page with the browser extension active. Click IDE in the extension popup (or enable auto-send in settings). You should see data appear in the NetTrace AI Output panel.
  7. Ask AI — open Cursor's chat (Ctrl+L) and ask naturally: "What requests did NetTrace capture?" or "Fix the 500 error from my browser." Cursor will call the NetTrace MCP tools automatically.

Setup for VS Code

VS Code uses native Language Model Tools that are registered automatically when the extension activates. No extra MCP config needed.

  1. Install the extension — install NetTrace AI — IDE Companion from the VS Code Marketplace, or search for NetTrace AI in the Extensions panel.
  2. Connect your account — open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P), run NetTrace: Connect Account, and paste your device token from nettrace.ai/dashboard/extension-setup.
  3. Verify the receiver — the status bar should show NetTrace: Listening or NetTrace: Connected (N).
  4. Send a request — browse any page with the browser extension active. Click IDE in the popup or enable auto-send.
  5. Use tools in chat — open VS Code Chat (Ctrl+Shift+I) and type # to see the NetTrace tools in autocomplete. For example: "Fix the 500 error using #nettracelog"

VS Code tool reference: type #nettracelog, #nettracefail, or any tool name with # in the chat panel to reference it directly.

Commands

All commands are available from the Command Palette. Below is the complete list:

Command
Description
Connect Account
Link your IDE to your NetTrace account using a device token.
Disconnect Account
Remove the stored device token and disconnect from NetTrace.
Start Local Receiver
Start the localhost HTTP server that receives requests from the browser extension.
Stop Local Receiver
Shut down the local receiver server.
Show Latest Failure
Open the most recent failed request (4xx/5xx) in a detailed view.
Copy Latest Failure Context
Copy the latest failure as AI-ready markdown to your clipboard.
Insert Latest Failure Context
Insert the latest failure context directly into your active editor.
Show All Requests
Open a panel showing every captured request in the current session.
Clear Local Data
Delete all locally stored request data from the IDE companion.
Show MCP Setup
Display MCP configuration instructions for clients that use MCP definitions.
Refresh Entitlement
Re-check your subscription status with the NetTrace server.
Show Entitlement Status
Display your current plan, trial status, and feature access.
Pair Browser Extension
Generate a pairing code to link the browser extension to this IDE instance.

Sidebar

The NetTrace IDE Companion adds a bug icon to the Activity Bar. Click it to open the NetTrace sidebar, which organizes captured data into three categories:

  • Sessions — grouped by browser capture session.
  • Failures — only 4xx and 5xx responses for quick triage.
  • All Requests — every captured request in chronological order.

Output Channel

Open the Output panel in VS Code or Cursor and select NetTrace AI from the channel dropdown. This shows receiver logs, connection events, and diagnostic messages.

06 · Asking AI About Your Requests

The IDE companion exposes tools that your AI assistant can call to access captured browser data. How you invoke them depends on your editor:

Cursor: Tools are called automatically via MCP. Just ask naturally — e.g. "fix the 500 error from NetTrace" — and the AI calls the right tool. Requires .cursor/mcp.json setup (see above).

VS Code: Type # in the chat panel to reference tools directly — e.g. "fix the error using #nettracelog". No extra config needed.

Available Tools

Eight tools are available. In Cursor they are called automatically via MCP. In VS Code, type # in chat to see them in autocomplete:

  • #nettracelog — compact reproduction context with failures first, request/response bodies, user actions, and console errors.
  • #nettracefail — the most recent failure cluster with triggering action, failed requests, and errors.
  • #nettracesession — the latest browser debug session with all requests and metadata.
  • #nettracerequests — lists all captured requests across sessions (method, URL, status, timing).
  • #nettracerequest — full detail for a specific request by ID, including headers and bodies.
  • #nettracesessions — overview of all capture sessions with request and failure counts.
  • #nettracefails — overview of all failure clusters across sessions.
  • #nettracehealth — check receiver status and connection count.

Example Prompts

Cursor (just ask naturally):

Fix the 500 error on the profile endpoint
What requests did NetTrace capture?
Find slow API calls and optimize them

VS Code (use # to reference tools):

Fix the error using #nettracelog
Look at #nettracefail and write a fix
Check #nettracerequests for slow calls

Key difference: Cursor uses MCP — tools are called automatically when you ask about browser requests. Requires a one-time .cursor/mcp.json setup. VS Code uses native Language Model Tools — type # in chat to reference tools. Works out of the box.

07 · Troubleshooting

Common issues and how to resolve them.

Extension Not Capturing Requests

  • Open Settings and confirm capture is enabled.
  • Check that you have completed the first-time consent prompt.
  • Verify your privacy scope includes the site you are browsing. If set to "Localhost", only local addresses are captured.
  • Make sure the relevant capture types (XHR, Fetch, etc.) are toggled on.

Response Body Shows "No Body"

  • On Firefox, cached responses may not expose a body to extensions. Hard-reload the page (Ctrl+Shift+R / Cmd+Shift+R) to bypass the cache.
  • Confirm that Capture response bodies is enabled in settings.
  • If the response exceeds the max body size setting, it will be truncated. Increase the limit if needed.

IDE Not Receiving Requests

  • Check the status bar in VS Code / Cursor for NetTrace: Connected. If it shows disconnected, run NetTrace: Connect Account again.
  • Run NetTrace: Start Local Receiver from the Command Palette if the receiver is not running.
  • The receiver listens on port 48731. Ensure your firewall or VPN is not blocking localhost traffic on this port.

"Send Failed" in Browser Extension

  • This means the browser extension could not reach the IDE receiver. Make sure your IDE (VS Code or Cursor) is running with the NetTrace companion installed.
  • Run NetTrace: Start Local Receiver in your IDE and try sending again.
  • If you recently restarted your IDE, the receiver may need a moment to start. Wait a few seconds and retry.

AI Tools Not Working

  • Cursor: AI tools require MCP configuration. If you haven't created .cursor/mcp.json, run NetTrace: Show MCP Setup from the Command Palette and follow the steps. Make sure your device token is set in the config and you've reloaded the window.
  • VS Code: Type # in the chat panel to reference tools (e.g. #nettracelog). If tools don't appear, reload the window.
  • The local receiver must be running for tools to return data. Check the status bar or run NetTrace: Start Local Receiver.
  • Ensure you have an active premium subscription or are within your 30-day trial.

"Premium Required" Message

  • IDE companion features, auto-send, and AI tools require an active premium subscription.
  • Visit the Billing page to manage your subscription or start a trial.
  • If you believe your subscription is active, run NetTrace: Refresh Entitlement in your IDE to re-check with the server.

Need more help? Email support@capstralabs.com and include the browser/IDE version, the output from the NetTrace AI Output channel, and a screenshot of the issue.