npx wrapper causes "EOF" errors in strict MCP clients (Antigravity, etc.)

[meghanto]

The recommended configuration uses npx -y @perplexity-ai/mcp-server. npx often writes installation logs ("Need to install the following packages...") or update checks to stdout. Since the MCP protocol requires stdout to be reserved exclusively for JSON-RPC messages, this extra text breaks the handshake, resulting in an immediate initialize: EOF error.

The Workaround: The reliable fix is to install the package locally (npm install @perplexity-ai/mcp-server) and point the config directly to the node executable and the script, bypassing the npx wrapper entirely.
** Before (Cursor/NPX style):**

{
  "perplexity": {
    "command": "npx",
    "args": ["-y", "@perplexity-ai/mcp-server"],
    "env": { "PERPLEXITY_API_KEY": "..." }
  }
}

** After (Antigravity/Direct Execution style):**

{
  "perplexity": {
    "command": "/usr/local/bin/node", 
    "args": [
      "/absolute/path/to/project/node_modules/@perplexity-ai/mcp-server/dist/index.js"
    ],
    "env": { "PERPLEXITY_API_KEY": "..." }
  }
}

[The above is a summary of my troubleshooting session with Gemini Pro 3, generated by Gemini Pro 3]

[meghanto]

I believe this should be a part of the FAQs of the readme as an alternative way of setting things up.
I am happy to submit a PR with this documentation update if you agree!

[kesku]

Apologies for my delay in response. Yes, please feel free to submit! This may be good to have between "Claude Desktop and "Other MCP Clients".

[kesku]

Antigravity has since updated how it handles this, so this may no longer be necessary for that specific client (Cursor/NPX style works now!). But the -yq flag is documented in our Troubleshooting section for any other strict clients that might have similar issues.