Perplexity Agent MCP

Source: https://code.j4k.dev/j4k-oss/perplexity-agent-mcp. github.com/Jercik/perplexity-agent-mcp is a read-only mirror; open issues and pull requests on the Forge.

An opinionated, coding-specialized, Model Context Protocol server that integrates Perplexity AI's Sonar models into AI coding assistants like Claude Code or Codex CLI. It's deliberately lean and adds very few tokens to your context. It covers quick API fact-checks and deeper research; How it works describes the tools.

Setup

The package is published only as @j4k-oss/perplexity-agent-mcp on the code.j4k.dev registry. The unscoped perplexity-agent-mcp package on npmjs is deprecated and gets no updates.

Always map the @j4k-oss scope to the code.j4k.dev registry: without a mapping, npm looks on npmjs, finds nothing, and fails with a 404. To do that once for every command, add this line to ~/.npmrc:

@j4k-oss:registry=https://code.j4k.dev/api/packages/j4k-oss/npm/

The inline flag in the commands below is enough for a single npx run. Keep the ~/.npmrc line for the global install: npm update -g and npm outdated -g read the registry from your configuration, so without the line they look the scoped name up on npmjs.org. Install the package globally:

npm install -g --@j4k-oss:registry=https://code.j4k.dev/api/packages/j4k-oss/npm/ @j4k-oss/perplexity-agent-mcp

If you installed the unscoped package globally, run npm uninstall -g perplexity-agent-mcp (or pnpm remove -g perplexity-agent-mcp) first: both packages provide the perplexity-agent-mcp command, npm refuses to overwrite it, and pnpm keeps running the old copy. To check the latest release without installing it:

npx -y --@j4k-oss:registry=https://code.j4k.dev/api/packages/j4k-oss/npm/ @j4k-oss/perplexity-agent-mcp@latest --version

In a pnpm project, map the scope to its registry and exempt it from minimumReleaseAge in pnpm-workspace.yaml, then add the package:

registries:
  "@j4k-oss": https://code.j4k.dev/api/packages/j4k-oss/npm/
minimumReleaseAgeExclude:
  - "@j4k-oss/*"

pnpm add -D @j4k-oss/perplexity-agent-mcp

The package installs the perplexity-agent-mcp command and reports the MCP server name perplexity-agent-mcp.

Then add it to your Claude config file (~/.claude.json or ~/.config/claude/config.json):

"mcpServers": {
  "perplexity": {
    "command": "perplexity-agent-mcp",
    "env": {
      "PERPLEXITY_API_KEY": "your-api-key-here"
    }
  }
}

Restart Claude Code after saving, and you're ready to go.

How it works

The server exposes only two tools with concise descriptions (~1.3K tokens), keeping your context window lean and efficient:

• lookup: Gets quick facts from documentation (like API syntax or config keys)
• answer: Does deeper research to compare options and make recommendations

Under the hood, both tools are opinionated wrappers that call Perplexity API with coding-specialized system prompts. The lookup tool uses a compact fact‑extraction prompt focused on code/docs facts (see LOOKUP_SYSTEM_PROMPT in src/prompts.ts). The answer tool uses a technical decision/analysis prompt tailored for migrations and architecture choices (see ANSWER_SYSTEM_PROMPT in src/prompts.ts). Each tool calls a fixed Perplexity model chosen for its task, and callers cannot select another. The models are set in registerLookupTool (src/tools/lookup.ts) and registerAnswerTool (src/tools/answer.ts).

Example AI agent prompt that will trigger AI agent to use this MCP and give you good results:

Please update the "foo" dependency to the latest version. Use Perplexity for the migration guide.

Requirements

• Node.js v24.15.0 or newer
• A Perplexity API key