bugsee · krassx · Sep 4, 2026 · Sep 4, 2026
diff --git a/docs/mcp/configuration.md b/docs/mcp/configuration.md
@@ -5,7 +5,7 @@ sidebar_position: 1
 slug: "/mcp/configuration"
 ---
 
-There are two ways to connect an MCP client to the Bugsee MCP server. Pick whichever your client supports — the resulting capabilities are identical.
+There are two ways to connect an MCP client to the Bugsee MCP server. Pick whichever your client supports — both reach the same tools and the same data your account can already see.
 
 - **OAuth 2.1** — paste a single URL (`https://api.bugsee.com/mcp`) into the client. The client opens a browser, you sign in to Bugsee, approve the connection once, and the client receives a scoped, rotating access token. No long-lived secret lives on the user's machine. Recommended for any client that supports it.
 - **Personal access token** — generate a token from the Bugsee dashboard and paste a URL that embeds it (`https://api.bugsee.com/mcp/<token>`) into the client config. Use this for clients that don't yet support OAuth, or for unattended setups (CI agents, scripts).
@@ -27,7 +27,7 @@ To connect:
 3. Bugsee asks you to confirm the connection and shows the application name supplied by the client.
 4. Approve. The client receives an access token (typically valid 1 hour, refreshed silently) and is now connected.
 
-The granted scope is **`mcp:read`** — read-only access to your Bugsee account. See [Security](/mcp/security) for details on the OAuth flow, scopes, and revocation.
+The default granted scope is **`mcp:read`** — read-only access to your Bugsee account. A client may additionally request **`mcp:write`**, which unlocks `create_application`; when it does, the consent screen shows the request and you can narrow the approval back to `mcp:read` before approving. See [Security](/mcp/security) for details on the OAuth flow, scopes, and revocation.
 
 ### Managing OAuth sessions
 

diff --git a/docs/mcp/index.md b/docs/mcp/index.md
@@ -9,7 +9,7 @@ The [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol) is a
 
 ## Bugsee MCP server
 
-The Bugsee MCP server gives any MCP-aware AI agent secure, scoped access to your Bugsee data — issues (crashes, errors, and user-submitted bug reports) and builds (app/install size, dependency changes, build-timing regressions, and dependency vulnerabilities) — without the developer leaving the agent's chat or editor. Combined with a code assistant that has access to your local source tree, this enables an end-to-end workflow: the agent fetches the issue or build, reads the stack trace or regression, locates the relevant files, and proposes a fix in the same conversation.
+The Bugsee MCP server gives any MCP-aware AI agent secure, scoped access to your Bugsee data — issues (crashes, errors, and user-submitted bug reports), builds (app/install size, dependency changes, build-timing regressions, and dependency vulnerabilities), and debug symbols — without the developer leaving the agent's chat or editor. Combined with a code assistant that has access to your local source tree, this enables an end-to-end workflow: the agent fetches the issue or build, reads the stack trace or regression, locates the relevant files, and proposes a fix in the same conversation.
 
 ## What you can do with it
 
@@ -19,6 +19,8 @@ The Bugsee MCP server gives any MCP-aware AI agent secure, scoped access to your
 - **Bug-report to PR**: turn a user-submitted bug report into a proposed code change without leaving the IDE.
 - **Build health**: check a build's app/install size, see what a release added or removed, and catch size, dependency, or build-timing regressions against the baseline.
 - **Dependency vulnerabilities**: read a build's vulnerability-scan summary and the diff versus the previous scan, or queue a fresh scan.
+- **Symbolication diagnostics**: when a crash still shows raw addresses, look up the module UUID to see whether its debug symbols were never uploaded, are still processing, or came through broken.
+- **App onboarding**: create a new application and get its app token to drop straight into the SDK initialization — for clients granted the `mcp:write` scope.
 
 See [Usage](/mcp/usage) for concrete example prompts.
 

diff --git a/docs/mcp/security.md b/docs/mcp/security.md
@@ -73,7 +73,7 @@ The Bugsee MCP server exposes two scopes:
 | `mcp:read` | Read access to the eleven read-only tools, scoped to the user's accessible applications. Equivalent to what the user sees in the Bugsee dashboard. |
 | `mcp:write` | Additionally permits [`create_application`](/mcp/usage#create_application). Still subject to organization admin or explicit `app_create` permission — the scope alone does not grant it. |
 
-`mcp:read` is the default scope. Future scopes will be additive and explicitly requested by clients.
+`mcp:read` is the default scope: a client that self-registers via Dynamic Client Registration without naming a scope is registered for `mcp:read` only, so a client that never asked for write access cannot present a consent screen requesting it. When a client does request `mcp:write`, the consent screen shows it and you can narrow the approval back to `mcp:read` before approving. Future scopes will be additive and explicitly requested by clients.
 
 [`trigger_build_vuln_scan`](/mcp/usage#trigger_build_vuln_scan) is authorized by the `modify` permission on the target application rather than by a distinct scope; a client holding only `mcp:read` on an account without `modify` cannot queue a scan.
 

diff --git a/docs/mcp/usage.md b/docs/mcp/usage.md
@@ -1,6 +1,6 @@
 ---
 title: "Usage"
-description: "Reference for the Bugsee MCP tools — applications, issues, and builds — plus example prompts and common workflows for triage, root-cause analysis, regression hunting, vulnerability scanning, and bug-to-PR loops."
+description: "Reference for the Bugsee MCP tools — applications, issues, builds, and symbols — plus example prompts and common workflows for triage, root-cause analysis, regression hunting, vulnerability scanning, and bug-to-PR loops."
 sidebar_position: 2
 slug: "/mcp/usage"
 ---
@@ -14,7 +14,7 @@ The Bugsee MCP server exports thirteen tools across four resource families. All
 | Applications | [`list_applications`](#list_applications) | Discover application keys |
 | Applications | [`create_application`](#create_application) | Create a new application and return its `app_token` (mutating) |
 | Issues | [`list_issues`](#list_issues) | Paginated issue listing with filters |
-| Issues | [`get_issue`](#get_issue) | Full issue report with optional logs and per-thread stacks |
+| Issues | [`get_issue`](#get_issue) | Full issue report with optional logs, attributes, and per-thread stacks |
 | Issues | [`get_issue_resource`](#get_issue_resource) | Presigned URL for an issue resource (video, screenshot, network log, attachment, native crash artifact, …) |
 | Builds | [`list_builds`](#list_builds) | Paginated build listing with filters |
 | Builds | [`list_latest_builds`](#list_latest_builds) | One build per `(package_id, format, build_configuration)` lineup |
@@ -37,8 +37,8 @@ List all applications accessible to the current user. Takes no parameters.
 | `key` | Application key used in issue keys (e.g., `MYAPP` in `MYAPP-123`) |
 | `name` | Display name |
 | `description` | Free-form description (may be empty) |
-| `type` | `ios`, `android`, or `web` |
-| `subtype` | Wrapper / framework if any (e.g., `react_native`, `flutter`, `unity`, `dotnet`, `xamarin`, `cordova`, `kmp`) |
+| `type` | Platform: `ios`, `android`, `javascript`, `rust`, or `web` (`web` is legacy — retained for existing applications, not creatable) |
+| `subtype` | Wrapper / framework if any (e.g., `react_native`, `flutter`, `unity`, `dotnet`, `xamarin`, `cordova`, `kmp`); empty for native apps |
 
 Use this tool first when the agent doesn't yet know which application key to query.
 
@@ -64,36 +64,42 @@ The returned `app_token` is a credential: it authorizes SDK builds to report int
 
 ### list_issues
 
-List issues for a given application. Returns a paginated response (50 issues per page).
+List issues for a given application, including unsymbolicated (missing-symbols) crashes and errors alongside ready ones. Returns a paginated response (50 issues per page).
 
 **Parameters:**
 
 | Parameter | Type | Required | Description |
 |---|---|---|---|
 | `application_id_or_key` | string | Yes | The application ID or key (e.g., `"MYAPP"`) |
 | `type` | string | No | Filter by issue type: `"bug"`, `"error"`, or `"crash"` |
-| `status` | string | No | Filter by issue status: `"open"` or `"closed"` |
+| `status` | string | No | Filter by issue open/closed state (not symbolication status): `"open"` or `"closed"` |
 | `version` | string | No | Filter by application version (e.g., `"1.2.3"`) |
 | `reporter_email` | string | No | Filter by reporter email address |
 | `sort` | string | No | Sort order. One of: `"date_desc"` (default), `"date_asc"`, `"events_desc"`, `"events_asc"`, `"users_desc"`, `"users_asc"` |
 | `cursor` | string | No | Pagination cursor from a previous response to fetch the next page |
 
 **Response fields:**
 
-- `issues` — array of issues, each containing `id`, `key`, `type`, `status`, `severity`, `summary`, `created_on`, `updated_on`; plus `events_count` and `users_count` for crashes/errors, or `description` for bugs
+- `issues` — array of issues, each containing `id`, `key`, `type`, `status`, `symbolication_status`, `severity`, `summary`, `created_on`, `updated_on`; plus `events_count` and `users_count` for crashes/errors, or `description` for bugs
 - `total` — total number of matching issues
 - `nextCursor` — present if more pages exist; pass it as `cursor` to fetch the next page
 
+`symbolication_status` is `"ready"` when the issue is symbolicated (or needs no symbols) and `"missing_sym"` when it is still waiting on debug symbols or source maps. Unsymbolicated issues often have an **empty `key`** until symbols are uploaded and processing completes — in that case pass the `id` field to `get_issue` / `get_issue_resource` as `issue_id` rather than `issue_key`, and use [`get_symbol_by_uuid`](#get_symbol_by_uuid) to find out what is missing.
+
+Log data is not available from this tool — use [`get_issue`](#get_issue) with `include_logs` for that.
+
 ### get_issue
 
-Get a single issue by its key (e.g., `"MYAPP-123"`). Returns a plain-text report with markdown sections covering timing, environment, summary, exception details, and optionally per-thread stacks and logs.
+Get a single issue by its key (e.g., `"MYAPP-123"`) or by its ID. Returns a plain-text report with markdown sections covering timing, environment, summary, exception details, and optionally per-thread stacks, app-defined attributes, and logs.
 
 **Parameters:**
 
 | Parameter | Type | Required | Description |
 |---|---|---|---|
-| `issue_key` | string | Yes | The issue key in `"APPKEY-NUMBER"` format (e.g., `"MYAPP-123"`). Use `list_issues` first to discover available keys. |
+| `issue_key` | string | Conditional | The issue key in `"APPKEY-NUMBER"` format (e.g., `"MYAPP-123"`). Required unless `issue_id` is given. Use `list_issues` first to discover available keys. |
+| `issue_id` | string | Conditional | Mongo ObjectId hex of the issue — the `id` field from `list_issues`. Required unless `issue_key` is given. Prefer this for unsymbolicated (`missing_sym`) issues, which have an empty key. |
 | `include_all_threads` | boolean | No | When `true`, include stack traces for **all** threads in the crash dump, not just the crashed/target thread. Useful for diagnosing deadlocks, thread-related crashes, or cases where the crashed thread alone does not explain the failure. Native iOS/Android dumps may contain dozens of threads, so response size grows accordingly. No effect on bug-type issues. Default: `false`. |
+| `include_attributes` | boolean | No | When `true`, add an **Attributes** section with the app-defined key/value context the SDK attached to the session (set through `setAttribute` — user tier, feature flags, tenant, …). Useful when the failure looks configuration- or account-dependent. Attributes are unbounded and app-defined, so an app that attaches many of them grows the response accordingly. Default: `false`. |
 | `include_logs` | object | No | Log filter configuration. If omitted, logs are **not** included. See below. |
 
 **Log filter options** (`include_logs`):
@@ -119,6 +125,9 @@ Get a single issue by its key (e.g., `"MYAPP-123"`). Returns a plain-text report
 - **Runtime** — React Native, Flutter, Unity, etc. (if applicable)
 - **Summary** — issue title
 - **Description** — bug reports only
+- **Labels** — labels the SDK attached to the report, when there are any
+- **Attributes** — app-defined key/value context; only when `include_attributes=true`
+- **Report source** — how the report was triggered (screenshot, shake, crash, `code_upload`, …), plus the capture mechanism and the calling code's origin when the SDK reported them. Reads `not reported` for SDK builds that predate trigger reporting.
 - **Exception** — crash/error type, signal, reason, stack trace of the crashed/target thread
 - **All threads** — only when `include_all_threads=true`; one subsection per thread with the crashed thread marked
 - **Memory leak analysis** — only when the issue carries a memory/thread-leak bundle (leaks arrive as `error`-type issues); covers the leaking class, retained size, GC-root reference chain, and a memory snapshot
@@ -134,7 +143,8 @@ For `"attachment"` the response always contains a **list** (an issue may carry m
 
 | Parameter | Type | Required | Description |
 |---|---|---|---|
-| `issue_key` | string | Yes | The issue key in `"APPKEY-NUMBER"` format. |
+| `issue_key` | string | Conditional | The issue key in `"APPKEY-NUMBER"` format. Required unless `issue_id` is given. |
+| `issue_id` | string | Conditional | Mongo ObjectId hex of the issue — the `id` field from `list_issues`. Required unless `issue_key` is given. Prefer this for unsymbolicated issues, which have an empty key. |
 | `resource_type` | string | Yes | One of: `"video"`, `"screenshot"`, `"log"`, `"network"`, `"breadcrumbs"`, `"viewtree"`, `"input"`, `"events.system"`, `"events.user"`, `"traces.system"`, `"traces.user"`, `"attachment"`, `"crash"`, `"minidump"`, `"crash.trace"`, `"crash.tombstone"`, `"performance"`, `"memory.leak"`. |
 
 For text-based log analysis prefer `get_issue` with `include_logs` — it returns filtered log entries inline without an HTTP fetch round trip. The `"memory.leak"` bundle is also rendered inline by `get_issue` (the **Memory leak analysis** section); fetch it via this tool only when you need the raw structured JSON.
@@ -324,12 +334,6 @@ Look up debugging symbols by module UUID — a dSYM, ELF, PDB, R8/ProGuard mappi
 
 Without `application_id_or_key`, org-owned hits are still limited to applications the caller can read.
 
-## Prompts
-
-> Note: While most AI agents that support the MCP Protocol also support tools, prompts are less widely adopted and may not be available in your AI agent of choice.
-
-* **/bugsee_fix** — when invoked from an agent that supports MCP prompts, pulls the supplied issue key and walks the agent through analyzing and proposing a fix.
-
 ## Example prompts by workflow
 
 The patterns below are what most users will write into their agent of choice. They map naturally onto the tools above, so an MCP-aware model can handle them without any custom wiring on your side.
@@ -416,6 +420,24 @@ If the user wants to re-check a build against the current advisory databases (e.
 
 A `"queued"` outcome means the agent should poll `list_build_vulnerabilities` after a few minutes. `"cooldown"` means wait `retry_after_minutes`. `"already_in_progress"` means another scan is in flight — poll, don't re-trigger.
 
+### 10. Diagnose an unsymbolicated crash
+
+When `list_issues` returns an issue with `symbolication_status="missing_sym"` and an empty `key`, the agent fetches it by `issue_id` and checks which module is missing symbols.
+
+> *"MyApp has crashes that aren't symbolicated — pull one and tell me which symbol file we forgot to upload."*
+>
+> *"Is anything uploaded for debug UUID 8A3F1C2E-…? Show me its status."*
+
+`get_symbol_by_uuid` returns matches in **any** status, so it distinguishes "never uploaded" from "uploaded but still processing" or "broken" — the usual reason a crash sits in `missing_sym`.
+
+### 11. Onboard a new app
+
+With the `mcp:write` scope granted, the agent can create the application and wire the SDK in one pass.
+
+> *"Create a Bugsee app called Checkout Service for iOS with key CHECKOUT, then add the SDK launch call to my AppDelegate using the returned token."*
+
+`create_application` returns the `app_token`, which the agent drops straight into the SDK initialization in your working tree. This still requires organization-admin (or `app_create`) rights on your account.
+
 ## Worked example
 
 A crash was deliberately planted within a test iOS app that had Bugsee pre-configured. Once triggered, the crash was intercepted and symbolicated by Bugsee, and a new issue was created (**IOS-1443**):