Skip to content

external-mcp-clients.md

Latest commit

 

History

History
50 lines (33 loc) · 3.45 KB

external-mcp-clients.md

File metadata and controls

50 lines (33 loc) · 3.45 KB

Troubleshooting: External MCP Clients

"External" = anything outside VS Code itself: Claude Code, Antigravity, Codex CLI, Cursor (when run as its own app), JetBrains MCP integrations, etc.

TL;DR

Use the default stdio-daemon-proxy transport generated by the VS Code Perplexity dashboard. The launcher script (~/.perplexity-mcp/start.mjs) attaches to the long-running daemon spawned by the VS Code extension; the daemon owns vault credentials, you don't have to.

If your client says "Vault locked" or you see "DAEMON_UNREACHABLE" in stderr, see the matching section below.

Symptom: "Vault locked: no keychain, no env var, no TTY"

This means your client's launcher process tried to read the vault directly — which only happens when daemon attach failed AND your launcher silently fell back to in-process stdio. Fix in 0.8.41 and later: the default launcher no longer falls back silently; you'll see "DAEMON_UNREACHABLE" instead. If you're seeing this on 0.8.40 or earlier, upgrade.

Symptom: "Perplexity MCP: cannot reach the extension-managed daemon" (DAEMON_UNREACHABLE)

The daemon is not running or not reachable. Three remediations, in order of likelihood:

  1. Reload the VS Code window. The extension respawns a healthy daemon on activation. After the dashboard shows "Daemon: running", retry from your external client.

  2. Switch this client's transport to http-loopback in the VS Code dashboard's MCP Config Management. This sidesteps the launcher entirely. Note: port-drift across daemon restarts is a known limitation tracked for 0.8.43; if it bites you, switch back to stdio-daemon-proxy after a daemon restart.

  3. Advanced: opt into in-process stdio. Set PERPLEXITY_NO_DAEMON=1 in this client's MCP env block. Then run:

    npx perplexity-user-mcp setup-vault

    This generates a passphrase + persistence snippet so the in-process server can unseal the vault in your client's runtime.

    Sync-folder warning: if the persistence snippet writes the env var into a synced shell rc file (Dropbox, OneDrive, iCloud Drive), the passphrase syncs too. Use a User-scope env var (Windows setx, macOS plist, Linux ~/.profile) for client-only env-block persistence.

Per-IDE support matrix

IDE Transport Status Smoke evidence
Claude Code stdio-daemon-proxy Supported (0.8.41) Pending — see smoke-tests.md
Antigravity stdio-daemon-proxy Supported (0.8.41) Pending
Codex CLI stdio-daemon-proxy Supported (0.8.41) Pending
Cursor (outside VS Code) stdio-daemon-proxy Supported (0.8.41) Pending
Claude Desktop stdio-daemon-proxy / http-tunnel Supported See main README
LM Studio UI-only Manual config See main README

The "Pending" rows fill in as 0.8.41 smoke runs land in docs/smoke-tests.md.

Why the daemon owns the credentials

Putting the vault passphrase into every IDE's MCP config would mean (a) plaintext secrets in JSON files that often live in synced folders, (b) divergent setups across IDEs, (c) credential rotation requires editing N configs. By concentrating unsealing in the extension-managed daemon, the configs stay credential-free; rotation is one dashboard click.

Related