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

# TestDino MCP Troubleshooting

> Fix common MCP server setup, connection, and authentication issues.

<Callout icon="book-open" color="#3B82F6">
  **What you'll learn**

  * How to fix installation and editor configuration issues
  * How to resolve authentication and token errors
  * How to troubleshoot data lookup and network problems
</Callout>

Resolve MCP server installation, editor configuration, authentication, and data lookup errors.

## Quick Reference

| Symptom                              | Likely Cause                             | Jump to                                   |
| :----------------------------------- | :--------------------------------------- | :---------------------------------------- |
| `npm ERR! 404 Not Found`             | Package name wrong or registry issue     | [Installation](#installation-issues)      |
| `command not found: testdino-mcp`    | Global bin not on PATH                   | [Installation](#installation-issues)      |
| Server not appearing in editor       | Config file path or JSON syntax          | [Editor Integration](#editor-integration) |
| `health` returns "Invalid token"     | Token expired, revoked, or missing scope | [Authentication](#authentication)         |
| `health` returns "No projects found" | Token has no project access              | [Authentication](#authentication)         |
| `Run not found` or empty results     | Wrong project, filters too narrow        | [Data Lookup](#data-lookup)               |
| `ECONNREFUSED` or timeout            | Network block or firewall                | [Network](#network-errors)                |

## Installation Issues

<AccordionGroup>
  <Accordion title="npm ERR! 404 Not Found - testdino-mcp">
    The package name is incorrect or your npm registry is misconfigured.

    Verify the package exists:

    ```bash theme={null}
    npm view testdino-mcp
    ```

    If this returns package info, the registry is fine. Check for typos in your MCP config. If it returns a 404, check your npm registry setting:

    ```bash theme={null}
    npm config get registry
    ```

    It should be `https://registry.npmjs.org/`.
  </Accordion>

  <Accordion title="command not found: testdino-mcp">
    Your npm global bin directory is not on your PATH.

    Find where npm installs global packages:

    ```bash theme={null}
    npm config get prefix
    ```

    Add the `bin` subdirectory to your PATH. On macOS/Linux:

    ```bash theme={null}
    export PATH="$(npm config get prefix)/bin:$PATH"
    ```

    Or skip the issue entirely by using `npx`:

    ```bash theme={null}
    npx -y testdino-mcp
    ```
  </Accordion>

  <Accordion title="EACCES: permission denied during global install">
    macOS and Linux may block global installs without elevated permissions.

    Fix by changing npm's default directory:

    ```bash theme={null}
    mkdir ~/.npm-global
    npm config set prefix '~/.npm-global'
    export PATH=~/.npm-global/bin:$PATH
    ```

    Or use `npx` instead of a global install. It requires no special permissions.
  </Accordion>
</AccordionGroup>

## Editor Integration

<AccordionGroup>
  <Accordion title="Claude Code: server not registered after claude mcp add">
    Verify the server was added:

    ```bash theme={null}
    claude mcp list
    ```

    If `testdino` does not appear, re-run the add command. Pass the token through the `TESTDINO_PAT` environment variable, which is what the server reads:

    ```bash theme={null}
    claude mcp add testdino --env TESTDINO_PAT=your-token -- npx -y testdino-mcp@latest
    ```

    A token passed only as a `--pat` flag is ignored, so the server connects but fails authentication with a "Missing TESTDINO\_PAT" error. Check that your token is correct and set as the environment variable.
  </Accordion>

  <Accordion title="Cursor: TestDino not showing in Settings → MCP">
    1. Open your config file and validate JSON syntax (trailing commas, missing brackets):

    ```bash theme={null}
    # macOS/Linux
    cat ~/.cursor/mcp.json | python3 -m json.tool

    # Or check project-level config
    cat .cursor/mcp.json | python3 -m json.tool
    ```

    2. Confirm the file path Cursor reads. Common locations:
       * Project: `.cursor/mcp.json`
       * macOS/Linux home: `~/.cursor/mcp.json`
       * Windows: `%APPDATA%\Cursor\mcp.json`

    3. Restart Cursor fully. Quit and reopen, not just reload window.

    4. Go to **Settings → Tools & MCP** and check if TestDino appears.
  </Accordion>

  <Accordion title="Claude Desktop: server not detected after restart">
    1. Confirm config file location for your OS:
       * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
       * Windows: `%APPDATA%\Claude\claude_desktop_config.json`
       * Linux: `~/.config/Claude/claude_desktop_config.json`

    2. Verify `npx` works in your terminal:

    ```bash theme={null}
    npx -y testdino-mcp --help
    ```

    3. Restart Claude Desktop completely (quit from system tray/dock, reopen).
  </Accordion>
</AccordionGroup>

## Authentication

<AccordionGroup>
  <Accordion title="health returns: Invalid token or Unauthorized">
    The token is expired, revoked, or was copied incorrectly.

    1. Go to **app.testdino.com → User Settings → Personal Access Tokens**
    2. Check the token's expiration date and status
    3. If expired or revoked, generate a new token
    4. Copy the new token and update your MCP config
    5. Restart your MCP client
    6. Run `health` again
  </Accordion>

  <Accordion title="health returns: No projects found or empty project list">
    The token exists but has no project access granted.

    1. Go to **app.testdino.com → User Settings → Personal Access Tokens**
    2. Click the eye icon next to your token to view its scope
    3. Ensure at least one project has **Test runs** or **Manual tests** access enabled
    4. If you just created the project, you may need to regenerate the token with the new project included
  </Accordion>

  <Accordion title="health succeeds but tools return Permission denied">
    The token has project access but not for the specific module.

    * `list_testruns` and `get_run_details` require **Test runs** module access
    * `list_manual_test_cases` and related tools require **Manual tests** module access

    Generate a new token with both modules enabled if you need access to both.
  </Accordion>
</AccordionGroup>

## Data Lookup

<AccordionGroup>
  <Accordion title="list_testruns returns empty results">
    Filters may be too narrow. Try widening your query:

    * Remove `by_branch`, `by_environment`, or `by_author` filters
    * Extend `by_time_interval` to `weekly` or `monthly`
    * Confirm you are querying the correct project

    If the project is new and has no uploads yet, results will be empty.
  </Accordion>

  <Accordion title="get_run_details returns: Run not found">
    * The `testrun_id` may be from a different project than what the token can access
    * If using `counter`, provide the correct `projectId` or project name alongside it
    * Use `list_testruns` first to confirm the run exists and get its exact ID
  </Accordion>

  <Accordion title="debug_testcase returns no failure data">
    The `debug_testcase` tool aggregates historical execution data. If the test case has only run once or has no recorded failures, there is not enough data for root cause analysis.

    Run the test case across multiple runs to build a failure history before using `debug_testcase`.
  </Accordion>
</AccordionGroup>

## Network Errors

<AccordionGroup>
  <Accordion title="ECONNREFUSED or connection timeout">
    The MCP server cannot reach TestDino APIs.

    1. Check internet connectivity:

    ```bash theme={null}
    curl -I https://app.testdino.com
    ```

    2. If behind a corporate firewall or VPN, ensure outbound HTTPS (port 443) to `*.testdino.com` is allowed

    3. Check the [Cloud Endpoints](/data-privacy/cloud-endpoints) page for the full list of domains to allowlist
  </Accordion>

  <Accordion title="Rate limiting errors (429)">
    Reduce query scope:

    * Use specific filters instead of `get_all=true`
    * Lower `limit` values
    * Avoid rapid sequential calls. Add short delays between queries.

    If rate limiting persists, contact [support@testdino.com](mailto:support@testdino.com).
  </Accordion>
</AccordionGroup>

## Still Stuck?

<CardGroup cols={2}>
  <Card title="Discord" icon="discord" href="https://discord.gg/hGY9kqSm58">
    Join the community for real-time help
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@testdino.com">
    Email [support@testdino.com](mailto:support@testdino.com)
  </Card>
</CardGroup>