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:
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.
The MCP server registers a tool named report_bug. When your agent decides a bug needs reporting, it can call it directly:
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(...)
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(...)
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
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:
{
"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
- The report is stored in the
bug_reports table.
- A dashboard notification fans out to every configured maintainer account.
- The maintainer team triages and updates
status through new → triaged → in_progress → resolved (or dismissed / duplicate).
- 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.