Understand.io

AI Assistants (MCP)

Overview

Understand.io runs a Model Context Protocol (MCP) server. MCP lets AI assistants such as Claude, ChatGPT, Cursor, VS Code and Windsurf read your errors, stack traces and logs directly.

Once connected, you can ask questions like "Show me the latest production errors" or "Why did this exception happen?" and the assistant looks up the answer in your Understand.io projects.

  • Read-only - assistants cannot change error statuses, settings or data.
  • Sign in with Understand.io - you approve each assistant in your browser.
  • No API keys - there is nothing to copy or store.

Requirements

AI assistants are available on paid plans. They are not included in the free trial. If your project is on the trial, the project owner can upgrade from the subscription page.

Server URL

You can find the server URL in your project under Settings → AI Assistants (MCP), with a copy button:

https://app.understand.io/mcp

Connecting Your Assistant

Claude

  1. In Claude (web or desktop), open Settings → Connectors and click Add custom connector.
  2. Name it Understand.io and paste the server URL.
  3. Click Connect and approve access in the window that opens.

Claude Code

Run this in your terminal:

claude mcp add --transport http understand https://app.understand.io/mcp

Then run /mcp in Claude Code, choose understand → Authenticate, and approve access in your browser.

ChatGPT

  1. In ChatGPT, open Settings → Apps & Connectors → Advanced settings and turn on Developer mode.
  2. Back in Apps & Connectors, click Create, paste the server URL and choose OAuth as the authentication.
  3. Sign in to Understand.io and approve access when asked.

Cursor

Add this to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
    "mcpServers": {
        "understand": {
            "url": "https://app.understand.io/mcp"
        }
    }
}

Open Cursor Settings → Tools & MCP, click Connect next to understand and approve access in your browser.

VS Code

Add this to .vscode/mcp.json:

{
    "servers": {
        "understand": {
            "type": "http",
            "url": "https://app.understand.io/mcp"
        }
    }
}

Start the server from the file or the MCP view. VS Code asks you to sign in and opens the approval page. The file contains no secrets, so it is safe to commit.

Windsurf

Add this to ~/.codeium/windsurf/mcp_config.json:

{
    "mcpServers": {
        "understand": {
            "serverUrl": "https://app.understand.io/mcp"
        }
    }
}

Click Refresh under Cascade → Manage MCPs and sign in when Windsurf asks.

Other Clients

Any MCP client that supports the Streamable HTTP transport with OAuth can connect:

Setting Value
URL https://app.understand.io/mcp
Transport Streamable HTTP (POST)
Authentication OAuth 2.1 with PKCE and dynamic client registration (discovered automatically)

To test the connection, run the MCP Inspector, choose Streamable HTTP, enter the URL and use Open Auth Settings → Quick OAuth Flow:

npx @modelcontextprotocol/inspector

Signing In

The first time the assistant connects, it opens an Understand.io page in your browser. Log in if needed, check which assistant is asking, and click Allow access.

The assistant then acts as you: it sees the same projects you can see, and nothing else.

Example Questions

  • "Show me the latest production errors in my project."
  • "Explain why the most frequent error this week occurred and how to fix it."
  • "Find errors similar to this one and tell me if they share a root cause."
  • "What else happened during the request that caused this exception?"
  • "Triage today's open errors and tell me what to fix first."

Tools

All tools are read-only. Times are in UTC, and every error and event includes a url back to the Understand.io dashboard. project_id is optional when you only have one project.

Tool Description
get_projects Lists the projects you can read. Each has an id to pass as project_id to the other tools.
get_project One project's details: platform, team size, connected issue tracker, open/fixed/ignored error counts and environments active in the last 30 days.
get_recent_errors The most recently seen error groups, newest first, with occurrences, affected users, severity and a 14-day daily trend. Filter by environment and status (defaults to open).
search_errors Finds error groups by keyword, environment, tag, time range (since, or from/to) or event field filters.
search_logs Searches individual log events by keyword, request_id, correlation_id, user_id, session_id, severity, environment and time range. Use order: "oldest" with a request_id to read a request in order.
summarize_error Incident summary for one error group: priority, impact, trend, the first application stack frame, root-cause hints, next steps and similar errors.
get_error_details Everything about one error group: full stack trace with source code, request data (secrets masked), user, environment, breadcrumbs, tags, recent occurrences and team comments.

Filters use the format field:operator:value, where the operator is ==, !=, >= or <=. For example:

["user_id:==:42", "method:==:post"]

A typical investigation goes like this:

  1. get_projects to find the project id.
  2. get_recent_errors or search_errors to find an error_id.
  3. summarize_error for impact, trend and likely cause.
  4. get_error_details for the full stack trace and request data.
  5. search_logs with the request_id to see everything that happened during that request.

Resources

Resource Description
docs://errors Reference for assistants: projects, error groups and statuses, event fields, search syntax and the investigation workflow.
project://{project_id}/settings Project configuration: name, platform, team members and roles, connected issue tracker and auto-ticketing.
environment://{project_id}/{environment} Health of one environment over the last 7 days: event volume, error volume, last event time and the busiest error groups.
errors://{project_id}/metadata Overview of a project's errors: totals by status, environments, busiest groups this week and the fields accepted by the search tools.

Prompts

Clients that support MCP prompts offer these as ready-made commands:

Prompt Description
analyze-exception Root-cause analysis of one error group (error_id). Loads the error, stack trace, request data and impact, and asks for the root cause, a fix, affected components and a recommendation.
triage-recent-errors Loads the most recent open errors of a project (optionally one environment) and asks for a prioritised list with likely causes and the first thing to fix.

Security

  • Read-only. Assistants cannot change error statuses, settings or data.
  • Assistants sign in with OAuth. You approve each one on an Understand.io page, and no passwords or keys are shared with it.
  • Access follows your team membership. Leaving a project removes the assistant's access to it too.
  • Passwords, tokens, cookies, API keys and card data in request payloads are masked before they reach the assistant.
  • Each assistant is limited to 120 requests per minute.
  • Access tokens expire after 7 days and are refreshed automatically. After 90 days you sign in again.

Managing Connected Assistants

Go to Settings → AI Assistants (MCP) to see every assistant connected to your account and when it was connected. Click Disconnect to remove an assistant's access immediately.