Bug/Feature Reporting

Reference for enabling report_bug and request_feature on a self-hosted mcpgate. The tools accept a bug or feature submission via MCP and forward it to a backing tracker.

Backends

Two mutually exclusive backends are supported. Pick one in the Bug Reporting service card of the Setup-Wizard:

  • Relay (default) — POSTs to https://api.mcpgate.de/feedback/report. The relay anonymizes the reporter, creates an issue on the upstream tracker, and emails the reporter on follow-up activity. Reports go to the upstream maintainers; the operator does not triage them.
  • Direct — POSTs the report straight to a GitLab project the operator owns. The operator's team triages.

If neither backend is configured, MCP discovery hides gateway_issue_*. FEEDBACK_MODE can be set to internal, mcpgate, or disabled to override the auto-detection — the Setup-Wizard's radio binds this env var directly.

Relay mode

No environment variables to set. Pick the radio in the wizard, click Save. The Setup handler auto-registers the gateway with the relay using the gateway's BASE_URL and the saving admin's session email, then persists the returned instance_token.

Re-saving relay mode with an existing token is a no-op — registrations aren't duplicated. If auto-registration fails (relay unreachable, missing BASE_URL or admin email), the failure is logged and the operator can re-save to retry.

Manual registration (rarely needed)

Skip this section unless you're pointing at a self-hosted relay or want to provision an instance token out-of-band.

curl -X POST https://api.mcpgate.de/feedback/register \
  -H "Content-Type: application/json" \
  -d '{
    "instance_url":     "https://mcpgate.your-domain.com",
    "admin_email":      "your-admin@your-domain.com",
    "consent_version":  1
  }'

Response:

{
  "instance_token": "9d922cdd07e66d6f...",
  "pong_delivery":  "email"
}

Set MCPGATE_FEEDBACK_INSTANCE_TOKEN to the returned token before starting the gateway. MCPGATE_FEEDBACK_URL points at https://api.mcpgate.de/feedback by default; override only for a self-hosted relay.

Pong delivery

How the relay notifies a reporter when there's news on their report:

  • email (default) — plain-text email from hello@mcpgate.de with the comment or release-version and a magic-link reply form.
  • local — the relay queues the notification and the operator's gateway pulls it via GET /feedback/pongs for delivery through whatever channel the operator has wired up (e.g. Slack DM via the gateway's existing bot integration). Set on the registration call.

Direct mode

Required environment variables (filled in via the Setup-Wizard's GitLab fields when Direct is selected):

  • GITLAB_ISSUE_TOKEN — project access token with api scope on the target project.
  • GITLAB_DEFAULT_PROJECT — project path (e.g. your-org/your-repo).
  • GITLAB_BASE_URL — e.g. https://gitlab.example.com.

Tool surface

  • report_bug — synchronous submit; returns {ok, ref, issue_iid}.
  • request_feature — same shape, type=feature.
  • Both accept anonymous: true to drop the reporter email — submission still lands as an issue but no follow-up notifications are possible.

Async events

Three events trigger reporter notifications on the relay path:

  • Maintainer comment on the issue — relay receives a GitLab webhook, dispatches an email or queues a local pong containing the comment plus a magic-link reply form.
  • Image released that closes referenced issues — relay receives POST /feedback/release from the upstream CI, fan-outs one notification per closed report.
  • Reporter erasure — magic-link in any relay email; clears the encrypted email and prevents further notifications. Issue history is preserved by hash.

Privacy posture

In relay mode the reporter's email is encrypted with AES-GCM at rest in the relay database; the upstream tracker only sees a HMAC-derived 12-character hash. Operators are responsible for disclosing this processing to their own users. See our privacy page for the relay's data-handling commitments.