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

# EdgeFinder CLI Troubleshooting Guide & Common Fixes

> Fix authentication errors, query limit warnings, MCP connection problems, and installation issues with EdgeFinder CLI and MCP server.

Most EdgeFinder problems fall into one of three categories: authentication, installation, or MCP configuration. This guide walks you through each scenario with the exact commands to resolve it so you can get back to your analysis quickly.

<AccordionGroup>
  <Accordion title="&#x22;No API key configured&#x22;">
    EdgeFinder cannot find a valid API key. You have three ways to fix this:

    **Option 1 — Run the interactive login flow (recommended):**

    ```bash theme={null}
    edgefinder login
    ```

    This prompts for your email, sends a magic link, and saves your API key automatically once you click through.

    **Option 2 — Set an environment variable:**

    ```bash theme={null}
    export EDGEFINDER_API_KEY=ef_live_...
    ```

    **Option 3 — Save directly to config:**

    ```bash theme={null}
    edgefinder config set api-key ef_live_...
    ```

    Your API key is stored in `~/.edgefinder/config.json`. The `EDGEFINDER_API_KEY` environment variable takes priority over the config file if both are set.
  </Accordion>

  <Accordion title="&#x22;Authentication failed&#x22; (401 error)">
    A 401 error means your API key is invalid or has been revoked. Your key may have been regenerated or the session that created it is no longer active.

    **Step 1 — Get a new API key:**

    Visit [chat.edgefinder.io/settings/integrations](https://chat.edgefinder.io/settings/integrations) and copy your current key.

    **Step 2 — Update your local config:**

    ```bash theme={null}
    edgefinder config set api-key <your-new-key>
    ```

    If you use the MCP server, update the `EDGEFINDER_API_KEY` value in your MCP client's config block as well, then restart the client.

    <Tip>
      Running `edgefinder login` again is the simplest way to refresh your credentials — it replaces the saved key automatically.
    </Tip>
  </Accordion>

  <Accordion title="&#x22;Monthly query limit reached&#x22; (403 error)">
    You have used all the queries included in your current plan for this billing period. EdgeFinder resets your query count at the start of each monthly billing cycle.

    To continue using EdgeFinder before the reset, upgrade your plan:

    1. Visit [chat.edgefinder.io/subscription](https://chat.edgefinder.io/subscription)
    2. Select a higher tier and complete checkout
    3. Your new limit takes effect immediately

    <Note>
      Your query count resets automatically each month. If you only occasionally hit the limit, waiting for the reset is a valid option.
    </Note>
  </Accordion>

  <Accordion title="Magic link not arriving in my inbox">
    If you don't see the magic link email within a minute or two:

    1. **Check your spam or junk folder** — authentication emails from EdgeFinder can end up there.
    2. **Note that magic links expire after approximately 10 minutes.** If yours expired, request a new one:

    ```bash theme={null}
    edgefinder login
    ```

    This starts a fresh login flow and sends a new magic link to your email address.
  </Accordion>

  <Accordion title="Login session expired">
    If the CLI reports that your login session has expired, the 10-minute authentication window closed before you clicked the magic link.

    Run the login command again to get a new link:

    ```bash theme={null}
    edgefinder login
    ```

    Click the new link promptly after it arrives.
  </Accordion>

  <Accordion title="MCP server is not connecting">
    If your MCP client (Claude Desktop, Openclaw, or another MCP-compatible tool) cannot connect to EdgeFinder, work through these checks in order:

    **1. Verify your API key is set in the MCP config**

    The MCP server reads credentials only from the `env` block in your client's config — it does not use your CLI config file. Your config should look like this:

    ```json theme={null}
    {
      "mcpServers": {
        "edgefinder": {
          "command": "npx",
          "args": ["-y", "@edgefinder/cli", "mcp"],
          "env": {
            "EDGEFINDER_API_KEY": "ef_live_..."
          }
        }
      }
    }
    ```

    **2. Restart your MCP client**

    Config changes do not take effect until you fully restart the client application.

    **3. Confirm Node.js 18 or later is installed**

    ```bash theme={null}
    node --version
    ```

    The output should show `v18.0.0` or higher. If it does not, install a newer version from [nodejs.org](https://nodejs.org).

    <Warning>
      If `EDGEFINDER_API_KEY` is missing from the `env` block, the MCP server exits immediately with an error and will not appear as a connected tool in your client.
    </Warning>
  </Accordion>

  <Accordion title="&#x22;Command not found: edgefinder&#x22;">
    The CLI is not installed or is not on your PATH. Fix it with a global install:

    ```bash theme={null}
    npm install -g @edgefinder/cli
    ```

    After installing, open a new terminal window and run `edgefinder --version` to confirm it works.

    **If you prefer not to install globally**, use `npx` to run any command without installing:

    ```bash theme={null}
    npx @edgefinder/cli ask "Who should I start this week?"
    ```

    **Check your Node.js version** if the install itself fails:

    ```bash theme={null}
    node --version
    ```

    EdgeFinder requires Node.js 18 or later. If your version is older, install a current release from [nodejs.org](https://nodejs.org) before retrying.
  </Accordion>

  <Accordion title="How do I check my current config and account status?">
    Run `edgefinder status` to see your account email, active subscription plan, and current query usage:

    ```bash theme={null}
    edgefinder status
    ```

    To inspect the raw config file directly, it lives at:

    ```
    ~/.edgefinder/config.json
    ```

    <Note>
      The config file stores your API key with permissions set to `600` (readable only by your user account).
    </Note>
  </Accordion>

  <Accordion title="How do I log out or reset my credentials?">
    Run the logout command to clear your saved API key from the config file:

    ```bash theme={null}
    edgefinder logout
    ```

    After logging out, any CLI command that requires authentication will prompt you to run `edgefinder login` again.
  </Accordion>
</AccordionGroup>