unravel.
Open dashboard

Docs · Features

AI agents (MCP)

Unravel exposes your production context to AI coding agents over the Model Context Protocol. Connect Claude Code (or any MCP client) to a project and the agent can pull the real trace behind a bug (SQL with bindings, exception stacktraces, the originating request) and fix the code with that context in hand. The loop is: an alert fires, you open your repo, ask "why is checkout failing?", and the agent reads the failing trace itself.

It's a read-only surface: the agent can look, never mutate. Access is available on paid plans (Solo and above).

Connecting

Create a key under Settings → API keys → AI agents in the dashboard. Each key is pinned to one environment of one project, shown to you exactly once, and can be revoked at any time.

The dashboard hands you a ready-to-run command. Run it in the root of the repository you want to debug - by default Claude Code adds the server in local scope, so it's available only to you, only in that project:

cd ~/code/my-app
claude mcp add --transport http unravel-production https://api.unravel.run/mcp \
  --header "Authorization: Bearer unrv_mcp_…"

The dashboard hands you this command with the server name already suffixed by the key's environment (unravel-production, unravel-staging, …) so a second key doesn't collide. That's the whole setup; there is nothing to install or version locally. Open claude in that directory and the Unravel tools are available.

Sharing with your team

The default local scope keeps the key to your machine. If you'd rather commit the connection so teammates pick it up automatically, use Claude Code's project scope (a .mcp.json at the repo root) - but don't hard-code the token there, or you'll commit a secret. Reference an environment variable instead in .mcp.json, and have each teammate set it in their shell:

{
  "mcpServers": {
    "unravel": {
      "type": "http",
      "url": "https://api.unravel.run/mcp",
      "headers": { "Authorization": "Bearer ${UNRAVEL_MCP_TOKEN}" }
    }
  }
}

Tools

Read-only tools, each backed by the same interpreted data the dashboard shows. List tools return compact JSON whose ids feed the detail tools; detail tools return the curated "AI paste" Markdown.

  • get_context - the project and environment this key is connected to, your plan, the limits that apply (data retention, max lookback), and a load snapshot of the last 24 hours: request volume and rate, error rate, p95, failed jobs, and how many routes, exceptions and queries are active. The agent calls this first to know what's available, and how busy the app is.
  • get_load_overview - the project-wide load picture: request volume and 5xx rate, p95 with its trend, the slowest routes, the heaviest SQL by total time, and the top exceptions. Where the traffic (and the breakage) concentrates, so the agent reads any single trace against real scale instead of in a vacuum.
  • search_traces - recent traces (request / job / command / scheduled task) with status, duration and route. Filter by route, errors-only, user, or type. The starting point for "what happened around X".
  • get_trace - the full timeline of one trace: spans, SQL, exceptions, the originating HTTP request, and detected insights (N+1, slow spans). A trace here follows the whole causal chain across process boundaries (the request, the queued jobs it dispatched, broadcasts and WebSocket delivery), so the agent sees an async failure end to end, not just the fragment where it surfaced. For HTTP traces it opens with a traffic-context line (how this route normally performs over the week leading up to it) so an outlier reads as an outlier.
  • compare_traces - a diff of a failing or slow trace against a healthy run of the same route, job or command: what changed in outcome, duration, query count and N+1 clusters, slow spans and outgoing calls. Pass a baseline trace or let it pick a representative good one for you. Root-cause analysis by comparison, the way an agent reasons best.
  • list_exceptions - exception groups deduplicated by fingerprint, with occurrence count and first/last seen.
  • get_exception - one group in depth: app-frame stacktrace, immediate cause, top messages and throw sites, affected routes and jobs, and sample traces to dig into with get_trace.
  • list_slow_queries - SQL query groups with call count and p50 / p95 / max duration, for finding slow or N+1-prone queries.
  • get_connection - one WebSocket connection's timeline: subscriptions, message frames, auth and errors. Each delivered message carries the id of the trace whose broadcast produced it, so the agent can jump straight to the request or job behind a realtime message, and back again.
  • get_channel - a broadcast channel: who's subscribed, and the recent broadcasts with the trace that emitted each one and how many connections it reached. A broadcast delivered to nobody is the usual tell for a wrong channel name or a missing subscriber.

On connect, the server also tells the agent how to use these together (which tool to reach for when chasing an exception, a slow request, or a query problem) so you don't have to spell out the workflow each time.

Scope and limits

A key only ever sees the one project and environment it was minted for, and only as far back as your plan's retention window, the same boundaries that apply in the dashboard. Responses are trimmed for an agent (no megabyte payload dumps), and the endpoint is rate-limited per project. Call get_context to read all of this back at runtime.

No sampling. Unravel captures every trace (minus known noise like scanner and health-check traffic), so within the retention window the agent sees the complete picture. It's still observability data, not a transactional system of record: for exact counts like financial reconciliation, your database is the source of truth.

Working across environments

Each key is pinned to one environment, and a connection has no cross-environment view. To let an agent see more than production, mint a separate key per environment and add each as its own server with a distinct name:

# production (in your app repo)
claude mcp add --transport http unravel-production https://api.unravel.run/mcp \
  --header "Authorization: Bearer unrv_mcp_…prod…"

# staging - a second key, a second server
claude mcp add --transport http unravel-staging https://api.unravel.run/mcp \
  --header "Authorization: Bearer unrv_mcp_…staging…"

The agent then has both toolsets (unravel-production and unravel-staging), each scoped to its environment. Likewise, the agent working on my-app should hold the key for the my-app project: the mapping is just which key you configured.