> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nofire.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot MCP

> The server does not appear, a tool returns nothing, or a token is rejected.

If you have not set the server up yet, start with [Install the MCP server](/mcp/getting-started).

<AccordionGroup>
  <Accordion title="MCP Server Not Responding" icon="circle-xmark">
    **Symptoms:** Commands timeout or show connection errors

    **For Cursor:**

    1. Check the MCP status icon in the bottom status bar
    2. Make sure that the JSON syntax in `~/.cursor/mcp.json` is valid
    3. Make sure that you fully quit and restarted Cursor, not just reloaded it
    4. Check API token is correct and active in NOFire AI dashboard
    5. Test connectivity: `curl https://mcp.nofire.ai/mcp/health`
    6. Look for errors in Cursor's developer console (Help → Toggle Developer Tools)

    **For Claude Desktop:**

    1. Make sure that the JSON syntax in `claude_desktop_config.json` is valid
    2. Make sure that the file path is correct for your operating system
    3. Check file permissions (should be readable)
    4. Make sure that the API token is active in the dashboard
    5. Check Claude's developer console for error messages
    6. Try removing and re-adding the configuration
  </Accordion>

  <Accordion title="JSON Syntax Errors" icon="code">
    **Symptoms:** MCP servers not loading, IDE shows configuration errors

    **Common mistakes:**

    ❌ **Missing comma between servers:**

    ```json theme={"dark"}
    {
      "mcpServers": {
        "server1": {...}  // Missing comma here!
        "NOFireAI": {...}
      }
    }
    ```

    ✅ **Correct:**

    ```json theme={"dark"}
    {
      "mcpServers": {
        "server1": {...},
        "NOFireAI": {...}
      }
    }
    ```

    **Check your JSON:**

    * Use an online JSON validator
    * Use command line: `python3 -m json.tool yourfile.json`
    * Most code editors have built-in JSON validation
  </Accordion>

  <Accordion title="API Token Issues" icon="key">
    **Symptoms:** "Invalid API token" or "Unauthorized" errors

    **Checklist:**

    1. Copy the API token correctly (no extra spaces or line breaks)
    2. Make sure that you copied the MCP key, not the agent key
    3. Make sure that the key is active in the NOFire AI dashboard
    4. Check key has not been deleted or deactivated
    5. Make sure quotes are proper JSON double quotes `""`

    **Test connectivity (no auth needed):**

    ```bash theme={"dark"}
    curl https://mcp.nofire.ai/mcp/health
    ```

    **Test your API token:**

    ```bash theme={"dark"}
    curl -X POST https://mcp.nofire.ai/mcp \
      -H "Authorization: Bearer your-key-here" \
      -H "Content-Type: application/json"
    ```

    If the health check works but auth fails, regenerate your API token in the dashboard.
  </Accordion>

  <Accordion title="Configuration File Not Found" icon="file-magnifying-glass">
    **Symptoms:** Cannot find `mcp.json` or `claude_desktop_config.json`

    **Solutions:**

    **For Cursor:**
    Create the directory and file if they do not exist:

    ```bash theme={"dark"}
    # macOS/Linux
    mkdir -p ~/.cursor
    touch ~/.cursor/mcp.json
    echo '{"mcpServers":{}}' > ~/.cursor/mcp.json

    # Windows (PowerShell)
    New-Item -Path "$env:APPDATA\.cursor" -ItemType Directory -Force
    '{"mcpServers":{}}' | Out-File "$env:APPDATA\.cursor\mcp.json"
    ```

    **For Claude Desktop:**

    ```bash theme={"dark"}
    # macOS
    mkdir -p ~/Library/Application\ Support/Claude
    echo '{"mcpServers":{}}' > ~/Library/Application\ Support/Claude/claude_desktop_config.json

    # Linux
    mkdir -p ~/.config/Claude
    echo '{"mcpServers":{}}' > ~/.config/Claude/claude_desktop_config.json

    # Windows (PowerShell)
    New-Item -Path "$env:APPDATA\Claude" -ItemType Directory -Force
    '{"mcpServers":{}}' | Out-File "$env:APPDATA\Claude\claude_desktop_config.json"
    ```
  </Accordion>

  <Accordion title="No Services Found" icon="magnifying-glass">
    **Symptoms:** "No entities found" or empty results

    **Solutions:**

    1. Make sure that your data sources are connected:
       * **If you use an observability stack**: make sure that the Grafana, Prometheus, and Loki connections are active
       * **If you use the Kubernetes agent**: make sure that the agent is deployed and running
    2. Wait for the first data collection, which also builds the production map
    3. If you use the agent, make sure that it has the correct cluster access
    4. Check connection logs for errors in the NOFire AI dashboard
  </Accordion>

  <Accordion title="Inaccurate File Mapping" icon="diagram-project">
    **Symptoms:** Files mapped to wrong services or not mapped at all

    **Solutions:**

    1. Use repository-qualified paths (include repo name)
    2. Make sure that the service names match the deployment labels
    3. Check if service was recently deployed (\< 1 hour)
    4. Fuzzy matching requires similar naming between files and services
  </Accordion>

  <Accordion title="API Token Permission Denied" icon="lock">
    **Symptoms:** "MCP keys are read-only" error

    **Issue:** You are trying to perform a write operation with an MCP key

    **Solution:** MCP keys are intentionally read-only for security. Write operations (like creating new services) require agent keys through the dashboard.
  </Accordion>
</AccordionGroup>

## Still stuck

Email [support@nofire.ai](mailto:support@nofire.ai) with the name of your IDE, the contents of your MCP configuration file with the token removed, and the error your IDE shows.