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

# Troubleshooting the peeps MCP server: common fixes

> Step-by-step solutions for the most common issues when connecting the peeps MCP server to Claude Desktop, Cursor, or other AI clients.

Most issues connecting peeps to your AI client come from one of three sources — API key problems, Node.js version mismatches, or client configuration errors. Work through the relevant section below to resolve your issue quickly.

<Accordion title="The MCP server is not showing up in my AI client">
  If the peeps MCP server doesn't appear in your AI client's tool list, check the following:

  1. **Verify your Node.js version.** The server requires Node.js 18 or later. Run the following command to check:

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

     If the version is below 18, [download the latest LTS release from nodejs.org](https://nodejs.org).

  2. **Validate your JSON config.** A single misplaced comma or bracket will prevent the config from loading. Paste your config into a JSON validator (such as [jsonlint.com](https://jsonlint.com)) and fix any errors.

  3. **Restart your AI client.** Configuration changes are only picked up on startup. Fully quit and reopen the client — don't just close the window.

  4. **Confirm `npx` is available in PATH.** Run the following to check:

     ```bash theme={null}
     which npx
     ```

     If `npx` is not found, reinstall Node.js or add it to your PATH manually.
</Accordion>

<Accordion title="I'm getting an 'Invalid API key' or 401 error">
  A 401 error means the server could not authenticate your request. Work through these checks:

  1. **Re-copy your API key.** Open the [peeps dashboard](https://app.peeps.ai), navigate to your API keys, and copy the key again. Paste it directly into your config to avoid typos.

  2. **Remove any surrounding whitespace or quotes.** The value of `PEEPS_API_KEY` must be the raw key string — no leading or trailing spaces, and no wrapping quote characters inside the environment variable value.

  3. **Check that the key hasn't been revoked.** In the dashboard, confirm the key is still active. If it was revoked, generate a new one and update your config.

  4. **For HTTP/SSE connections, verify the header format.** When connecting to `https://mcp.peeps.ai/sse`, the Authorization header must use the Bearer scheme:

     ```http theme={null}
     Authorization: Bearer YOUR_API_KEY
     ```
</Accordion>

<Accordion title="Search returns no results">
  If tool calls succeed but return empty results, the issue is likely with your data or query:

  1. **Confirm your workspace has synced data.** Log in to [app.peeps.ai](https://app.peeps.ai) and verify that contacts or people records are visible in your workspace. If the workspace is empty, no search will return results.

  2. **Try a broader search query.** Instead of searching by full name or email, try searching by just a first name or a partial company name to rule out over-filtering.

  3. **Check your API key's permissions.** Some keys may be scoped to specific data types. In the dashboard, confirm the key has read access to the data you're querying.
</Accordion>

<Accordion title="&#x22;command not found: npx&#x22; error">
  This error means the AI client cannot locate `npx` in the PATH it uses when spawning processes. The PATH available to desktop apps often differs from your terminal's PATH.

  1. **Find the full path to `npx`.** Run the following in your terminal:

     ```bash theme={null}
     which npx
     ```

     Use the full path (e.g. `/usr/local/bin/npx`) as the `command` value in your config instead of just `npx`.

  2. **Alternatively, install the package globally.** This places a named binary in a standard system location:

     ```bash theme={null}
     npm install -g @peeps-ai/mcp
     ```

     Then use `peeps-mcp` as the command in your client config instead of `npx`.
</Accordion>

<Accordion title="The MCP server starts but crashes immediately">
  A crash on startup is almost always caused by a missing or invalid `PEEPS_API_KEY`. Run the server manually in your terminal to see the full error output:

  ```bash theme={null}
  PEEPS_API_KEY=your-key npx -y @peeps-ai/mcp
  ```

  Replace `your-key` with your actual API key. If the server exits with an error, the message printed to stderr will identify the cause.

  You can also check your AI client's MCP logs directly:

  * **Claude Desktop:** Open the developer/logs panel from the Help menu.
  * **Cursor:** Check the Output panel and select the MCP or extension log stream.

  Once you have the error message, search for it in this guide or email it to [support@peeps.ai](mailto:support@peeps.ai).
</Accordion>

<Accordion title="Claude Desktop: config changes not taking effect">
  Claude Desktop caches its configuration at launch and does not reload it automatically.

  1. **Fully quit Claude Desktop.** On macOS, press **Cmd + Q** or right-click the Dock icon and choose **Quit** — closing the window leaves the app running in the background. On Windows, right-click the system tray icon and choose **Quit**.

  2. **Validate your JSON syntax.** Open your config file and check for syntax errors. Even a trailing comma will cause the file to be ignored silently.

     * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
     * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

  3. **Confirm you're editing the correct file path.** On macOS, `~/Library` is hidden by default in Finder. Use **Go → Go to Folder** in Finder and paste the path, or edit the file from your terminal to be sure you're in the right location.
</Accordion>

<Note>
  Still stuck? Email [support@peeps.ai](mailto:support@peeps.ai) with your error message and OS, and we'll help you out.
</Note>