Skip to main content
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.
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:
    If the version is below 18, download the latest LTS release from 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) 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:
    If npx is not found, reinstall Node.js or add it to your PATH manually.
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, 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:
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 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.
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:
    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:
    Then use peeps-mcp as the command in your client config instead of npx.
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:
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.
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.
Still stuck? Email support@peeps.ai with your error message and OS, and we’ll help you out.