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, bugs, hangs, 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.

---

Can MCP Modify or Write Data?

All current tools are read-only. MCP cannot create, update, or delete any data in your Luciq workspace.

---

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 allows 60 requests per minute per developer. Rate limits are per-user, not per-workspace - your usage doesn't affect teammates. If you hit the limit, wait briefly and retry.

---

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"

---

Still need help? Contact [email protected].