flyer-crawler.projectium.com/docs/BUGSINK-MCP-TROUBLESHOOTING.md

Bugsink MCP Troubleshooting Guide

This document tracks known issues and solutions for the Bugsink MCP server integration with Claude Code.

Issue History

2026-01-22: Server Name Prefix Collision (LATEST)

Problem:

• bugsink-dev MCP server never starts (tools not available)
• Production bugsink MCP works fine
• Manual test works: BUGSINK_URL=http://localhost:8000 BUGSINK_TOKEN=<token> node d:/gitea/bugsink-mcp/dist/index.js
• Configuration correct, environment variables correct, but server silently skipped

Root Cause: Claude Code silently skips MCP servers when server names share prefixes (e.g., bugsink and bugsink-dev). Debug logs showed bugsink-dev was NEVER started - no "Starting connection" message ever appeared.

Discovery Method:

• Analyzed Claude Code debug logs at C:\Users\games3\.claude\debug\*.txt
• Found that MCP startup messages only showed: memory, bugsink, redis, gitea-projectium, etc.
• bugsink-dev was completely absent from startup sequence
• No error was logged - server was silently filtered out

Solution Attempts:

Attempt 1: Renamed bugsink-dev to devbugsink

• New MCP tool prefix: mcp__devbugsink__*
• Changed URL from http://localhost:8000 to http://127.0.0.1:8000
• Result: Still failed after full VS Code restart - server never loaded

Attempt 2: Renamed devbugsink to localerrors (completely different name)

• New MCP tool prefix: mcp__localerrors__*
• Uses completely unrelated name with no shared prefix
• Based on infra-architect research showing name collision issues
• Result: Still failed after full VS Code restart - server never loaded

Attempt 3: Created project-level .mcp.json file ✅ SUCCESS

• Location: d:\gitea\flyer-crawler.projectium.com\flyer-crawler.projectium.com\.mcp.json
• Contains localerrors server configuration
• Project-level config bypassed the global config loader issue
• Result: ✅ Working! Server loads successfully, 2 projects found
• Tool prefix: mcp__localerrors__*

Alternative Solutions Researched:

• Sentry MCP: Not compatible (different API endpoints /api/canonical/0/ vs /api/0/)
• MCP-Proxy: Could work but requires separate process
• Project-level .mcp.json: Alternative if global config continues to fail

Status: ✅ RESOLVED - Project-level .mcp.json works successfully

Root Cause Analysis: Claude Code's global settings.json has an issue loading localhost stdio MCP servers, even with completely distinct names. The exact cause is unknown, but may be related to:

• Multiple servers using the same package (bugsink-mcp)
• Localhost URL filtering in global config
• Internal MCP loader bug specific to Windows/localhost combinations

Working Solution: Use project-level .mcp.json file instead of global settings.json for localhost MCP servers. This bypasses the global config loader issue entirely.

Key Insights:

1. Global config fails for localhost servers even with distinct names (localerrors)
2. Project-level .mcp.json successfully loads the same configuration
3. Production HTTPS servers work fine in global config
4. Both configs can coexist: global for production, project-level for dev

---

2026-01-21: Environment Variable Typo (RESOLVED)

Problem:

• bugsink-dev MCP server fails to start (tools not available)
• Production bugsink MCP works fine
• User experienced repeated troubleshooting loops without resolution

Root Cause: Environment variable name mismatch:

• Package expects: BUGSINK_TOKEN
• Configuration had: BUGSINK_API_TOKEN

Discovery Method:

• infra-architect subagent examined d:\gitea\bugsink-mcp\README.md line 47
• Found correct variable name in package documentation
• Production MCP continued working because it was started before config change

Solution Applied:

1. Updated C:\Users\games3\.claude\settings.json:

   • Changed BUGSINK_API_TOKEN to BUGSINK_TOKEN for both bugsink and bugsink-dev
   • Removed unused BUGSINK_ORG_SLUG environment variable

2. Updated documentation:

   • CLAUDE.md MCP Servers section (lines 307-327)
   • docs/BUGSINK-SYNC.md environment variables (line 66, 108)

3. Required action:

   • Restart Claude Code to reload MCP servers

Status: Fixed - but superseded by server name collision issue above

---

Correct Configuration

Required Environment Variables

The bugsink-mcp package requires exactly TWO environment variables:

{
  "bugsink": {
    "command": "node",
    "args": ["d:\\gitea\\bugsink-mcp\\dist\\index.js"],
    "env": {
      "BUGSINK_URL": "https://bugsink.projectium.com",
      "BUGSINK_TOKEN": "<40-char-hex-token>"
    }
  },
  "localerrors": {
    "command": "node",
    "args": ["d:\\gitea\\bugsink-mcp\\dist\\index.js"],
    "env": {
      "BUGSINK_URL": "http://127.0.0.1:8000",
      "BUGSINK_TOKEN": "<40-char-hex-token>"
    }
  }
}

Important:

• Variable is BUGSINK_TOKEN, NOT BUGSINK_API_TOKEN
• BUGSINK_ORG_SLUG is NOT used by the package
• Works with both HTTPS (production) and HTTP (localhost)
• Use completely distinct name like localerrors (not bugsink-dev or devbugsink) to avoid any name collision

---

Common Issues

MCP Server Tools Not Available

Symptoms:

• mcp__localerrors__* tools return "No such tool available"
• Production bugsink MCP may work while localerrors fails

Possible Causes:

1. Wrong environment variable name (most common)

   • Check: Variable must be BUGSINK_TOKEN, not BUGSINK_API_TOKEN

2. Invalid API token

   • Check: Token must be 40-character lowercase hex
   • Verify: Token created via Django management command

3. Bugsink instance not accessible

   • Test: curl -s -o /dev/null -w "%{http_code}" http://localhost:8000
   • Expected: 302 (redirect) or 200

4. MCP server crashed on startup

   • Check: Claude Code logs (if available)
   • Test manually: BUGSINK_URL=http://localhost:8000 BUGSINK_TOKEN=<token> node d:/gitea/bugsink-mcp/dist/index.js

Solution:

1. Verify correct variable names in settings.json
2. Restart Claude Code
3. Test connection: Use mcp__bugsink__test_connection tool

---

Testing MCP Server

Manual Test

Run the MCP server directly to see error output:

# For localhost Bugsink
cd d:\gitea\bugsink-mcp
set BUGSINK_URL=http://localhost:8000
set BUGSINK_TOKEN=a609c2886daa4e1e05f1517074d7779a5fb49056
node dist/index.js

Expected output:

Bugsink MCP server started
Connected to: http://localhost:8000

Test in Claude Code

After restart, verify both MCP servers work:

// Production Bugsink
mcp__bugsink__test_connection();
// Expected: "Connection successful: Connected successfully. Found N project(s)."

// Dev Container Bugsink
mcp__localerrors__test_connection();
// Expected: "Connection successful: Connected successfully. Found N project(s)."

---

Creating Bugsink API Tokens

Bugsink 2.0.11 does NOT have a "Settings > API Keys" menu in the UI. Tokens must be created via Django management command.

For Dev Container (localhost:8000)

MSYS_NO_PATHCONV=1 podman exec -e DATABASE_URL=postgresql://bugsink:bugsink_dev_password@postgres:5432/bugsink -e SECRET_KEY=dev-bugsink-secret-key-minimum-50-characters-for-security flyer-crawler-dev sh -c 'cd /opt/bugsink/conf && DJANGO_SETTINGS_MODULE=bugsink_conf PYTHONPATH=/opt/bugsink/conf:/opt/bugsink/lib/python3.10/site-packages /opt/bugsink/bin/python -m django create_auth_token'

For Production (bugsink.projectium.com via SSH)

ssh root@projectium.com "cd /opt/bugsink && bugsink-manage create_auth_token"

Both commands output a 40-character hex token.

---

Package Information

• Repository: https://github.com/j-shelfwood/bugsink-mcp.git
• Local Installation: d:\gitea\bugsink-mcp
• Build Command: npm install && npm run build
• Main File: dist/index.js

---

Related Documentation

• CLAUDE.md MCP Servers Section
• DEV-CONTAINER-BUGSINK.md
• BUGSINK-SYNC.md

---

Failed Solutions (Do Not Retry)

These approaches were tried and did NOT work:

1. ❌ Regenerating API token multiple times
2. ❌ Restarting Claude Code without config changes
3. ❌ Checking Bugsink instance accessibility (was already working)
4. ❌ Adding BUGSINK_ORG_SLUG environment variable (not used by package)

Lesson: Always verify actual package requirements in source code/README before troubleshooting.