> For the complete documentation index, see [llms.txt](https://docs.luciq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.luciq.ai/product-guides-and-integrations/product-guides/ai-features/luciq-mcp-server/faq-and-troubleshooting.md). # FAQ & Troubleshooting *** ## 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](/product-guides-and-integrations/product-guides/ai-features/luciq-mcp-server/authentication-and-security.md#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 29 tools should appear. Whether each one returns data depends on your role and plan, but they should all be listed *** Still need help? Contact . --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.luciq.ai/product-guides-and-integrations/product-guides/ai-features/luciq-mcp-server/faq-and-troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.