Ctrlk
Go To Luciq
For the complete documentation index, see llms.txt. This page is also available as Markdown.

FAQ & Troubleshooting

Answers to frequently asked questions and troubleshooting tips for the Luciq MCP Server. Resolve common setup issues and get the most out of AI debugging.

What does the MCP server do vs. what does the AI do?

The Luciq MCP server is a data bridge - it fetches structured data from your Luciq workspace (crashes, performance metrics, bugs, hangs, surveys, reviews) and hands it to your AI assistant. The MCP server doesn't analyze, summarize, or interpret anything.

Everything else - natural language understanding, pattern recognition, summarization, suggestions - comes from the AI model in your IDE. If a response feels inaccurate or speculative, that's the AI reasoning over the data, not the MCP returning bad data. Being more specific in your prompts (exact app names, time ranges, environments) gives the AI better data to work with.

Connection Problems

Can't connect to the MCP server

  • Verify the server URL: https://api.luciq.ai/api/mcp

  • Restart your IDE after adding or changing the MCP configuration

  • If using a VPN or corporate proxy, ensure api.luciq.ai is allowed through your firewall

  • If your organization uses a dedicated Luciq cluster, your endpoint URL may differ - contact your Luciq admin

OAuth isn't opening in my browser

  • Make sure your default browser allows pop-ups from your IDE

  • Try the connection again - some clients need a retry on first attempt

  • If using Claude Code over SSH or a remote terminal, interactive OAuth won't work. Use token-based authentication instead

Authorized OAuth but still can't connect

  • Restart your IDE after completing authorization

  • Verify your Luciq account is active and has the necessary permissions

"Tool not found" or "Method not found" Errors

Luciq MCP uses snake_case tool names: list_crashes, not listCrashes. If your AI is calling tools with the wrong naming convention, correct it in your prompt or verify the connection is active by asking: "List my applications."

Permissions and App Visibility

MCP respects your workspace's RBAC settings. If you're seeing "App not found" or not seeing all your apps, your account may not have permissions for those apps or environments. Check with your workspace admin.

If a specific tool returns a permission error (the message names the missing permission), your role doesn't have access to that data type, ask your workspace admin to grant it in your Luciq role settings.

"Not included in your plan"

If a tool returns a message that its product isn't included in your current plan, that tool's data type (for example APM, Surveys, or Crash Reporting) isn't part of your subscription. The tool still appears in your client's tool list (all 27 always do), but it can't run until the product is enabled on your plan. Contact your Luciq account team to add it.

The aggregated app_insights tool degrades gracefully here: any section for a product you don't have is simply omitted from the response, and the rest still come back.

"Application not found or not accessible"

This means the slug + mode combination you (or your assistant) used doesn't match an app you can access. Common causes: a typo in the slug, the wrong environment (production vs beta/staging), or no permission for that app. Ask your assistant to "list my applications" to get the exact slug and mode values, then retry.

Can MCP Modify or Write Data?

Almost all tools are read-only. The one tool that writes is update_bug, which can change a bug's triage state - its status, priority, tags, or mark/unmark it as a duplicate of another bug. This is the same action you'd take in the dashboard, exposed so agents can finish bug triage without a context switch.

Write actions:

  • Respect your RBAC permissions - you can only update bugs in apps and environments you already have access to (changing tags needs an extra tag-modify permission)

  • Are audit-logged - just like any change made in the dashboard

One read tool has a subtle side effect worth knowing: crash_diagnostics computes and caches a crash-analysis payload on demand, so it isn't a pure read (if it returns status: "generating", just ask again in a moment). It never changes your crash, bug, or app data.

No other tool creates, updates, or deletes data. MCP cannot touch your source code, account, or billing.

Slow Responses or Timeouts

If queries are taking unusually long or timing out:

  • Try narrower queries - add time ranges, specify the app, filter by environment

  • Avoid asking for very large result sets in a single query

  • Check your network connection to api.luciq.ai

Rate Limits

MCP requests are rate-limited per client (by IP), with a default of 100 requests per 60 seconds. If you hit the limit you'll get a 429 with Rate limit exceeded, wait briefly and retry. Normal conversational use rarely gets close; only tight automated loops do.

IDE-Specific Issues

Cursor: server shows as disconnected

  • Check ~/.cursor/mcp.json for valid JSON syntax (a missing comma or bracket will break it)

  • Restart Cursor after any configuration changes

  • Try removing and re-adding the Luciq server entry

Claude Code: "Transport error"

  • Ensure you used --transport http when adding the server

  • Try removing and re-adding: claude mcp remove luciq then add again

Claude Desktop: connection hangs or fails silently

  • Double-check the JSON syntax in your config file

  • Make sure the entry is inside the mcpServers object, not at the root level

  • Restart Claude Desktop completely (quit and reopen)

VS Code: tools not appearing in Copilot

  • Verify .vscode/mcp.json exists in your workspace root

  • Reload the window: Cmd/Ctrl + Shift + P > "Developer: Reload Window"

Any IDE: connected, but no Luciq tools show up

  • Make sure you completed the OAuth approval (or added valid Email/Token headers), an unauthenticated connection won't expose tools

  • Restart the IDE so it re-runs the tool discovery (tools/list) after authenticating

  • Confirm your role has MCP access enabled, without it the server rejects the session before any tools load

  • Once authenticated, all 33 tools should appear. Whether each one returns data depends on your role and plan, but they should all be listed

Still need help? Contact [email protected].

PreviousUse Cases & WorkflowsNextAgent Skills

Last updated