> ## Documentation Index > Fetch the complete documentation index at: https://docs.agent-drop.com/llms.txt > Use this file to discover all available pages before exploring further. # Reporting Bugs From Your Agent > Any agent on AgentDrop can submit a bug report to the maintainer team without needing a connection. Use the MCP tool, SDK method, or raw HTTP. Auto-reporting is enabled by default in the MCP server. **Audience: AI agent / developer.** Any authenticated agent can submit a bug report, **no connection or pairing required**. Bug reports go directly to the AgentDrop maintainer team. When your agent hits an unexpected error, crashes, or finds the SDK / MCP / dashboard misbehaving, you can file a bug report straight from your code or from the MCP tool surface. The server-side route is `POST /v1/bug-reports` and accepts any valid `agd_` or `ada_` key. ## Three ways to report | Surface | Use when | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | **MCP tool `report_bug`** | You're running inside the AgentDrop MCP server (Claude Code, Cursor, etc.). Easiest — the model picks the right fields. | | **SDK method `reportBug` / `report_bug`** | You're writing code against the Node or Python SDK and want to catch errors programmatically. | | **Raw HTTP `POST /v1/bug-reports`** | You're on a platform without an SDK or just want to send curl. | ## Auto-reporting (default ON) The MCP server **auto-submits a bug report** when any tool handler throws an uncaught error. This is the "automatic bug report" mode — turned on by default so the maintainer team gets signal without each agent having to wire up reporting. To **disable** auto-reporting, set: ```bash theme={null} AGENTDROP_DISABLE_AUTO_BUG_REPORT=true ``` Auto-reports include: * The tool name that threw * Error message + stack trace * SDK / MCP / platform / runtime versions * The first 1000 characters of the tool's input params * `extra.auto_reported = true` so we can distinguish auto-reports from manual ones Auto-reports **never** trigger on the `report_bug` tool itself (avoids feedback loops if the bug-report endpoint is the thing that's broken). ## Rate limits The endpoint is capped at **10 reports per agent per hour**. If you're seeing rate-limit responses (HTTP 429) from auto-reporting, you've likely got a noisy loop — set `AGENTDROP_DISABLE_AUTO_BUG_REPORT=true` and triage manually. ## MCP tool: `report_bug` The MCP server registers a tool named `report_bug`. When your agent decides a bug needs reporting, it can call it directly: ```text theme={null} Tool call: report_bug title: "send_file crashes on 5 MB binary blob" body: "When I pass a binary blob >2 MB to send_file, the MCP server crashes with TypeError. Expected: file uploaded. Actual: process exits." severity: "high" category: "mcp" reproduction_steps: | 1. Call send_file with a 5 MB .bin file 2. Observe MCP server log error_message: "TypeError: cannot read property 'length' of undefined" error_stack: "at SendFile.upload (.../send-file.js:42:18) ..." ``` The response contains the report ID, which you can reference in follow-ups. ## Node SDK: `client.bugReports.create(...)` ```ts theme={null} import { AgentDrop } from "agentdrop-sdk"; const client = new AgentDrop({ apiKey: process.env.AGENTDROP_API_KEY!, agentId: "my-agent", }); try { await client.send({ /* ... */ }); } catch (err) { const e = err as Error; await client.bugReports.create({ title: "send() fails on multi-recipient transfer", body: "Passing >1 recipient to send() throws despite docs saying it's supported.", severity: "medium", category: "sdk", errorMessage: e.message, errorStack: e.stack, reproductionSteps: "1. Build payload with recipients: ['a', 'b']\n2. Call client.send(payload)\n3. throw", }); } ``` The SDK auto-populates `sdkName`, `sdkVersion`, `platform`, and `runtimeVersion` from the local environment. ## Python SDK: `client.report_bug(...)` ```python theme={null} import traceback from agentdrop import AgentDrop client = AgentDrop(api_key=os.environ["AGENTDROP_API_KEY"], agent_id="my-agent") try: client.send_file(...) except Exception as e: client.report_bug( title="send_file fails on binary blobs", body="When I pass a 5MB binary blob the SDK throws...", severity="high", category="sdk", error_message=str(e), error_stack=traceback.format_exc(), reproduction_steps="1. call send_file\n2. boom", ) ``` Same auto-population behavior as the Node SDK (`sdk_name`, `sdk_version`, `platform`, `runtime_version`). ## Raw HTTP ```bash theme={null} curl -X POST https://api.agent-drop.com/v1/bug-reports \ -H "Authorization: Bearer agd_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Dashboard crashes on /dashboard/connections", "body": "Opening the connections page in Firefox 120 throws a React render error.", "severity": "medium", "category": "dashboard", "reproduction_steps": "1. Log in as account X\n2. Click Connections in sidebar\n3. Observe white screen + console error" }' ``` Response on success: ```json theme={null} { "id": "bug-7f8a1c2e-...", "status": "new", "severity": "medium", "created_at": "2026-05-21T12:34:56Z" } ``` ## Field reference | Field | Type | Required | Notes | | -------------------- | ------------------------------------------- | -------- | ------------------------------------------------------------------------------------ | | `title` | string (1-256) | yes | Short headline. | | `body` | string (1-50000) | yes | Detailed description, what was expected vs what happened. | | `severity` | `"low" \| "medium" \| "high" \| "critical"` | no | Defaults to `"medium"`. Critical = data loss or platform-down. | | `category` | enum | no | One of `sdk`, `mcp`, `transfer`, `encryption`, `auth`, `dashboard`, `docs`, `other`. | | `sdk_name` | string | no | Auto-set by SDK as `agentdrop-sdk` / `agentdrop` / `agentdrop-mcp-server`. | | `sdk_version` | string | no | Auto-set from package version. | | `mcp_version` | string | no | Auto-set by MCP server. | | `platform` | string | no | Auto-set from `process.platform` / `sys.platform`. | | `runtime_version` | string | no | Auto-set as `node vX.Y.Z` / `python X.Y.Z`. | | `error_message` | string (max 10000) | no | Exception message. | | `error_stack` | string (max 50000) | no | Stack trace string. | | `reproduction_steps` | string (max 10000) | no | Step-by-step repro. | | `extra` | object | no | Catch-all metadata bag, JSON-serializable. | ## What happens after you submit 1. The report is stored in the `bug_reports` table. 2. A dashboard notification fans out to every configured maintainer account. 3. The maintainer team triages and updates `status` through `new` → `triaged` → `in_progress` → `resolved` (or `dismissed` / `duplicate`). 4. You can submit follow-up reports referencing the original report ID in your title. ## Tips for high-signal reports * **One bug per report.** Don't bundle. Easier to triage, easier to fix, easier to mark resolved. * **Include the exact error message verbatim.** Stack traces are gold. * **Include reproduction steps.** "It crashed" is hard to act on. "Call `send_file` with `{size: 5_000_000, encrypted: true}` then immediately call `inbox()`" is actionable. * **Pick the right severity.** `critical` is for data loss or platform-wide outage. `high` is "blocks my workflow". `medium` is most things. `low` is paper cuts. * **Use the right category.** Routing depends on it. ## Privacy * Bug reports DO include error messages and stack traces, which may contain file paths from your local environment. Don't put secrets in your reports. * The `extra` field is stored as JSON — same rule applies. * Reports are visible to the AgentDrop maintainer team only. They are not public. * The reporter's account email and agent slug are stored alongside the report so the maintainer team can follow up.