# Bugfender MCP

Bugfender's hosted MCP service connects AI clients to Bugfender through remote
Streamable HTTP and OAuth:

```text
https://mcp.bugfender.com/mcp
```

The `@bugfender/mcp` npm package remains available as a deprecated local stdio
fallback for existing and self-hosted installations.

## What It Provides

- user-scoped Bugfender read access through MCP
- automatic access-token refresh when a refresh token is configured
- logs, devices, app metadata, crash aggregation, and issue aggregation tools
- SDK snippet retrieval for app onboarding
- resource templates for snippets, logs, and issue groups
- companion Bugfender skills distributed from `bugfender/bugfender-skills`

## Maintainers

- development workflow: [DEVELOPMENT.md](./DEVELOPMENT.md)
- release and publish flow: [RELEASING.md](./RELEASING.md)

## Recommended: hosted OAuth

In ChatGPT or Codex, install the public Bugfender plugin and connect the included
Bugfender app. In any compatible remote MCP client, add
`https://mcp.bugfender.com/mcp` and choose OAuth authentication.

The client discovers the protected resource and Bugfender authorization server,
opens the Bugfender sign-in and consent UI, and manages short-lived access and
refresh tokens. Hosted users must not manually copy an API token into the
connection.

### OAuth scopes

- `mcp:read` grants read-only access to identity, teams, apps, SDK metadata,
  logs, devices, crashes, issues, feedback, network data, and summaries the
  signed-in user can already access.
- `mcp:issues:write` grants only `update_issue_status`. It does not grant
  general Bugfender administration or other write operations.

### Disconnect and revoke

Use the client's Bugfender **Disconnect** action to revoke the hosted grant and
its access and refresh tokens. If a client lists the plugin and connection
separately, disconnect the connection before uninstalling the plugin. A future
tool call must start a new OAuth flow.

### Privacy

The hosted MCP forwards the request bearer token to the Bugfender API and
returns data the signed-in user is authorized to access. It does not persist
user credentials or expose them in tool results. The MCP client and AI provider
may separately process tool inputs and return Bugfender data under their own
privacy and retention terms. See Bugfender's
[Privacy Policy](https://bugfender.com/privacy-policy/) and
[Terms of Service](https://bugfender.com/terms-of-service/).

## Deprecated: local stdio package

Existing installations and clients without remote OAuth can continue to run:

```bash
npx -y @bugfender/mcp
```

Do not use this setup for a new public-cloud connection. Prefer the hosted URL
or public plugin instead.

After adding or updating the MCP server in your IDE or agent, restart that client so it reloads the new MCP configuration cleanly.

If you are running from inside this repository checkout, do not use `npx @bugfender/mcp` or `npx -p @bugfender/mcp bugfender-mcp`. npm can resolve the current package instead of the published tarball and fail with `bugfender-mcp: not found`.

For local development, build and run the generated entrypoint directly:

```bash
pnpm build
pnpm start
```

## Local stdio configuration

- `BUGFENDER_API_TOKEN`: required access token
- `BUGFENDER_REFRESH_TOKEN`: recommended for automatic token refresh
- `BUGFENDER_API_URL`: optional override, defaults to `https://dashboard.bugfender.com/api`
- `~/.bugfender/mcp.json`: optional config file and local token store for rotated credentials

```json
{
  "default": {
    "apiToken": "YOUR_ACCESS_TOKEN",
    "refreshToken": "YOUR_REFRESH_TOKEN",
    "apiUrl": "https://dashboard.bugfender.com/api"
  }
}
```

When a refresh token is provided, the MCP stores rotated credentials in `~/.bugfender/mcp.json` so automatic refresh survives restarts. Updating the IDE config with a newly generated refresh token resets that local state.

These credentials and the local token store apply only to the stdio executable.
The hosted HTTP executable reads a bearer token from each request and never
reads or writes `~/.bugfender/mcp.json`.

If you are using local or self-hosted Bugfender credentials, `BUGFENDER_API_URL` must point to the matching backend. For example, local credentials generated from `https://dashboard:3000` will not work against `https://dashboard.bugfender.com/api`.

### Legacy Cursor / Claude Code configuration

```json
{
  "mcpServers": {
    "bugfender": {
      "command": "npx",
      "args": ["-y", "@bugfender/mcp"],
      "env": {
        "BUGFENDER_API_TOKEN": "YOUR_ACCESS_TOKEN",
        "BUGFENDER_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN",
        "BUGFENDER_API_URL": "https://dashboard.bugfender.com/api"
      }
    }
  }
}
```

### Legacy Codex CLI configuration

```bash
codex mcp add bugfender \
  --env BUGFENDER_API_TOKEN='YOUR_ACCESS_TOKEN' \
  --env BUGFENDER_REFRESH_TOKEN='YOUR_REFRESH_TOKEN' \
  --env BUGFENDER_API_URL='https://dashboard.bugfender.com/api' \
  -- npx -y @bugfender/mcp
```

After running `codex mcp add`, restart the Codex session before testing `who_am_i` or `list_apps`.

### Legacy Gemini CLI configuration

```bash
gemini mcp add bugfender npx -y @bugfender/mcp \
  --env BUGFENDER_API_TOKEN='YOUR_ACCESS_TOKEN' \
  --env BUGFENDER_REFRESH_TOKEN='YOUR_REFRESH_TOKEN' \
  --env BUGFENDER_API_URL='https://dashboard.bugfender.com/api'
```

After running `gemini mcp add`, start a new Gemini CLI session or reload MCP servers before testing `who_am_i` or `list_apps`.

### Legacy Codex App configuration

In the custom MCP server form:

- `Name`: `bugfender`
- `Command to launch`: `npx`
- `Argument 1`: `-y`
- `Argument 2`: `@bugfender/mcp`
- `BUGFENDER_API_TOKEN`: `YOUR_ACCESS_TOKEN`
- `BUGFENDER_REFRESH_TOKEN`: `YOUR_REFRESH_TOKEN`
- `BUGFENDER_API_URL`: `https://dashboard.bugfender.com/api`

Add the arguments as separate rows, not as one combined string.

After saving the server, restart the app before testing `who_am_i` or `list_apps`.

## Hosted Streamable HTTP deployment

Build and start the HTTP entry point with:

```bash
pnpm build
pnpm start:http
```

It exposes:

- `POST /mcp`: stateless MCP Streamable HTTP endpoint
- `GET /healthz`: liveness check
- `GET /readyz`: readiness check

TLS is terminated by the production ingress. Every `/mcp` request must include
`Authorization: Bearer <token>`. The process creates an isolated MCP server and
Bugfender API client for that request; the token is neither shared nor persisted.

Hosted configuration:

- `BUGFENDER_API_URL` (default `https://dashboard.bugfender.com/api`)
- `BUGFENDER_MCP_HOST` (default `0.0.0.0`)
- `BUGFENDER_MCP_PORT` (default `3002`)
- `BUGFENDER_MCP_MAX_REQUEST_BYTES` (default `1048576`)
- `BUGFENDER_MCP_MAX_RESPONSE_BYTES` (default `524288`)
- `BUGFENDER_MCP_MAX_CONCURRENCY` (default `100`)
- `BUGFENDER_MCP_REQUEST_TIMEOUT_MS` (default `35000`)
- `BUGFENDER_MCP_SHUTDOWN_TIMEOUT_MS` (default `10000`)

The hosted entry point uses JSON response mode within the Streamable HTTP
protocol. It is intentionally stateless, so `GET` and `DELETE` on `/mcp` return
`405 Method Not Allowed`.

The production container can be built and exercised locally with:

```bash
docker build -t bugfender-mcp .
docker run --rm --read-only --tmpfs /tmp:rw,noexec,nosuid,size=16m \
  -p 3002:3002 bugfender-mcp
```

The image runs as UID/GID `10001`, writes structured JSON logs to stderr, and
exposes Prometheus metrics on `GET /metrics` for cluster-internal scraping.

Hosted mode publishes OAuth protected-resource metadata at
`GET /.well-known/oauth-protected-resource`. Authentication challenges point
clients to that document. Production defaults to resource
`https://mcp.bugfender.com`, issuer `https://app.bugfender.com`, and API
`https://app.bugfender.com/api`;
staging deployments must override `BUGFENDER_MCP_RESOURCE_URL` and
`BUGFENDER_OAUTH_ISSUER` and `BUGFENDER_API_URL` with their staging origins.
Documentation, privacy, and terms links can be overridden with `BUGFENDER_MCP_DOCUMENTATION_URL`,
`BUGFENDER_MCP_PRIVACY_POLICY_URL`, and `BUGFENDER_MCP_TERMS_URL`.

### Hosted authentication troubleshooting

- Use the exact endpoint `https://mcp.bugfender.com/mcp`; the OAuth resource is
  the origin `https://mcp.bugfender.com` without `/mcp`.
- Do not configure `BUGFENDER_API_TOKEN` or paste a bearer token into a remote-hosted connection.
- Disconnect and reconnect to recover from expired or revoked grants or to
  request different scopes.
- `update_issue_status` requires `mcp:issues:write`; investigation tools require
  `mcp:read`.
- A client must support remote Streamable HTTP, OAuth discovery, Authorization
  Code with PKCE, and resource indicators. Otherwise, use the deprecated local
  stdio fallback.
- Hosted OAuth currently supports Bugfender's public cloud. Self-hosted
  deployments must use local stdio and set `BUGFENDER_API_URL` to their backend.

## Tools

- `who_am_i`
- `list_teams`
- `list_apps`
- `get_app`
- `list_app_versions`
- `get_sdk_snippet`
- `get_crashes`
- `get_crash_stats`
- `get_crash_device_stats`
- `get_crash_details`
- `search_logs`
- `count_logs`
- `count_devices_with_logs`
- `get_network_aggregates`
- `get_network_details`
- `search_devices`
- `count_devices`
- `list_issues`
- `get_issue`
- `update_issue_status`
- `get_issue_stats`
- `get_issue_device_stats`
- `get_issue_devices`
- `get_feedback`
- `get_app_summary`

## Resources

- `bugfender://snippet/{app_id}/{platform}`
- `bugfender://app/{app_id}/logs?...`
- `bugfender://issue/{issue_id}?app_id={app_id}`

## Companion Skills

The companion skills now live in the separate [`bugfender/bugfender-skills`](https://github.com/bugfender/bugfender-skills) repository. They encode opinionated workflows on top of the MCP tools:

- use aggregation before logs
- narrow time ranges early
- size impact before deep-diving
- end with a short triage summary

The MCP package gives the agent raw Bugfender capabilities. The skill adds an opinionated investigation workflow on top of those capabilities.

Use the skill when you want Cursor, Codex, or Claude Code to do things like:

- help set up the Bugfender SDK in an app with the minimum required steps
- fetch the SDK snippet for a platform and explain exactly where it goes
- investigate the top crashes in an app
- summarize issue or feedback trends over a time range
- compare impact before and after an app version
- identify likely cause, scope, and next checks

The investigation skill source lives in:

- `https://github.com/bugfender/bugfender-skills/tree/main/skills/bugfender`

## SDK Setup Skill

The dedicated onboarding skill also lives in [`bugfender/bugfender-skills`](https://github.com/bugfender/bugfender-skills).

Use it when you want Cursor, Codex, or Claude Code to:

- detect the project platform automatically
- fetch the correct Bugfender SDK snippet
- map the setup to the real repository files
- ask one short feature question when optional capabilities like crash reporting or Android logcat matter
- apply the minimum integration changes
- reduce the developer’s work to one final verification step

It also includes platform-specific references for:

- iOS
- Android
- Flutter
- Unity
- .NET MAUI
- Cordova
- Ionic
- Angular
- React
- Vue
- JavaScript
- jQuery
- Titanium
- Web
- React Native

The skill source lives in:

- `https://github.com/bugfender/bugfender-skills/tree/main/skills/bugfender-sdk-setup`

## Install Skills In Cursor, Codex, Or Claude Code

Cursor, Codex, and Claude Code can install the skills directly from GitHub without cloning the repo manually.

In the agent chat inside your IDE, run this prompt with the built-in installer skill:

```text
Use $skill-installer to install these skills from https://github.com/bugfender/bugfender-skills:
- skills/bugfender
- skills/bugfender-sdk-setup
```

After installation, restart the client and use:

```text
Use $bugfender-sdk-setup to set up Bugfender in this app with the minimum required changes.
```