Perplexity MCP: PERPLEXITY_API_KEY is required

Fix Perplexity MCP PERPLEXITY_API_KEY is required

TL;DR

Put PERPLEXITY_API_KEY in the env block of your MCP config. The server reads it from its own process environment, and clients do not inherit your shell's exports, so a key that works in your terminal is invisible to the server until you declare it there.

The exact error:

PERPLEXITY_API_KEY is required

Steps

1. Add the key to the MCP config

Edit your MCP config (claude_desktop_config.json for Claude Desktop) so the entry looks like this:

{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@jschuller/perplexity-mcp"],
      "env": { "PERPLEXITY_API_KEY": "[your Perplexity API key]" }
    }
  }
}

Success check: the JSON is valid (run it through a JSON linter if unsure) and the key has no surrounding spaces or quotes.

2. Check the key format

Perplexity API keys start with pplx-. If yours does not, you probably copied the wrong token (for example a browser session value).

Success check: the key starts with pplx-.

3. Restart the client completely

Quit the client fully. On macOS, Claude Desktop keeps helper processes alive after the window closes; end them or the old config stays loaded.

Success check: the perplexity tools (search_web, search_academic, etc.) appear in the tool list and a test query returns an answer.

When this applies

• The Perplexity MCP server fails to start and the log or client shows PERPLEXITY_API_KEY is required.
• You set the key in your shell or .env but never put it in the MCP client config.

When it does not apply

• The server starts but calls fail with 401 Unauthorized. That means the key reached the server but Perplexity rejected it: check for extra spaces, an expired key, or a key from the wrong account.
• You get 400 invalid_request_error on tool calls. Update the package to v2.1.0 or newer; older versions ship a schema Claude Code rejects.
• No module named 'fastmcp' on a Python-based variant. That is a missing dependency; reinstall requirements in the venv.

Tool compatibility

• @jschuller/perplexity-mcp npm package (npx)
• Python-based Perplexity MCP variants that read PERPLEXITYAPIKEY from the environment
• Claude Desktop, Claude Code, Cursor

Why it happens

MCP servers spawn as child processes of the client. A child process only sees the environment the client gives it, which is the env block in the config. Keys exported in your shell profile, set in a project .env, or typed into a terminal never cross that boundary, so the server exits with the "is required" error even though the key "is set" from your point of view.

Edge cases

• On Windows, some clients need the machine restarted (not just the app) before the new config is picked up.
• If you run the server via uvx or a custom script instead of npx, the same rule holds: the key must be in the environment of the spawned process.
• Storing the key in the config file is fine on a personal machine; on shared machines prefer a secrets manager that injects env vars for the client.