Client Integration

This page is an index and overview for connecting the Perplexity MCP Server to specific AI client applications. Detailed per-client setup is covered in subpages: Claude Desktop and Plugin Marketplace (see page 6.1), Cursor and VS Code (see page 6.2), Windsurf and Codex (see page 6.3), and Generic MCP Client Integration (see page 6.4). For environment variables and configuration options, see page 5. For deployment strategies, see page 7.

Overview

The Perplexity MCP Server supports integration with multiple client applications through two primary transport mechanisms:

Transport Type	Entry Point	Use Case	Clients
STDIO	src/index.ts	Local desktop applications	Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Codex
HTTP	src/http.ts	Remote/cloud deployments	Generic MCP clients, cloud IDE extensions

All integrations require the PERPLEXITY_API_KEY environment variable for authentication with the Perplexity API.

Sources: README.md1-181 README.md54-107

Installation Methods

The server supports multiple installation approaches depending on the client:

Method	Supported Clients	Details
One-click badge	Cursor, VS Code	Badge URLs encode base64 JSON config with command, args, and env placeholders
CLI command	Claude Code, Codex	claude mcp add / codex mcp add with --env flag
Plugin marketplace	Claude Code	/plugin install perplexity inside the Claude REPL
Manual JSON config	All clients	Edit the client-specific JSON config file directly

CLI commands:

Client	Command
Claude Code	claude mcp add perplexity --env PERPLEXITY_API_KEY="..." -- npx -y @perplexity-ai/mcp-server
Codex	codex mcp add perplexity --env PERPLEXITY_API_KEY="..." -- npx -y @perplexity-ai/mcp-server

For Claude Code plugin marketplace installation:

The marketplace manifest is defined in .claude-plugin/marketplace.json35-45

Sources: README.md39-107 .claude-plugin/marketplace.json1-48

Configuration File Formats

mcpServers Format

Used by Claude Desktop, Cursor, and Windsurf. Wraps server configuration in an mcpServers object:

Field	Description	Required
command	Executable to launch (typically npx)	Yes
args	Argument array passed to command	Yes
env	Environment variables injected into the server process	Yes

servers Format

Used by VS Code. Adds an explicit type field and uses a servers top-level key instead of mcpServers:

The "type": "stdio" field explicitly declares the transport mechanism.

Sources: README.md57-97

Configuration File Locations

Config File and Format by Client

Client	Configuration File	Format Key	type Field
Cursor	~/.cursor/mcp.json	mcpServers	Not required
Claude Desktop	claude_desktop_config.json	mcpServers	Not required
Windsurf	~/.codeium/windsurf/mcp_config.json	mcpServers	Not required
VS Code	.vscode/mcp.json	servers	Required ("stdio")

Sources: README.md59-97

STDIO Transport Integration

STDIO Process Lifecycle: Client → src/index.ts → src/server.ts

The -y flag auto-accepts NPX install prompts. Use -yq to suppress all stdout output from NPX itself — required by strict MCP clients that fail on non-JSON output on the channel.

NPX execution steps:

1. Client spawns npx with args ["-y", "@perplexity-ai/mcp-server"] and the env block from config
2. NPX resolves the package from the npm registry and caches it under ~/.npm
3. NPX executes the binary entry point (perplexity-mcp) defined in package.json
4. src/index.ts main() validates PERPLEXITY_API_KEY, calls createPerplexityServer(), attaches StdioServerTransport, and calls server.connect(transport)
5. The server reads MCP protocol messages from stdin and writes responses to stdout

Sources: README.md66-77 README.md86-96 README.md175-178

HTTP Transport Integration

For remote or shared deployments, clients connect to the /mcp endpoint exposed by src/http.ts instead of spawning a local process. The server uses StreamableHTTPServerTransport from @modelcontextprotocol/sdk/server/streamableHttp.js.

POST http://<host>:<port>/mcp ← MCP protocol messages (JSON)
GET http://<host>:<port>/health ← Health check

In this mode, PERPLEXITY_API_KEY must be set as an environment variable on the server side, not in the client configuration. See page 6.4 for generic HTTP client connection details and page 7.2 for running the HTTP server.

Sources: README.md140-168

Package Distribution

The server is distributed through the npm registry as @perplexity-ai/mcp-server. The MCP Registry manifest at server.json declares the package name, version, transport type, and a remote HTTP endpoint for clients that support registry-based discovery. See page 5.3 for full details on the manifest files.

Sources: README.md1-10

Environment Variable Passing

Environment variables in the client env block are injected into the spawned server process. Any variable from page 5.1 can be passed this way:

The .claude-plugin/marketplace.json manifest sets PERPLEXITY_TIMEOUT_MS to 600000 (10 minutes) by default via ${PERPLEXITY_TIMEOUT_MS:-600000}, which is higher than the global 5-minute default used in direct installations.

Sources: README.md33-38 .claude-plugin/marketplace.json41-43

Common Integration Issues

Symptom	Cause	Fix
EOF / Initialize errors	NPX writes install messages to stdout; strict clients fail on non-JSON	Use npx -yq instead of npx -y in args
PERPLEXITY_API_KEY not found	API key not set	Add key to the env block in client config
Tool not found	Wrong package name or no internet at first run	Verify package is @perplexity-ai/mcp-server; check internet access
Timeout on perplexity_research	Default 5-minute timeout too short for deep research	Set PERPLEXITY_TIMEOUT_MS=600000 in env
Network error behind corporate firewall	No proxy configured	Set PERPLEXITY_PROXY in env (see page 5.2)

Sources: README.md170-178

Client Compatibility

Client Installation Methods and Transport Mechanisms

Most clients use the mcpServers JSON wrapper pointing at npx -y @perplexity-ai/mcp-server. If a client does not work with the documented configuration, consult its documentation for its expected top-level key name.

Sources: README.md40-107 .claude-plugin/marketplace.json35-45

Server Discovery

The package is registered in the MCP Registry with metadata defined in server.json:

Field	Value
Name	io.github.perplexityai/mcp-server
Title	Perplexity API Platform
Description	Real-time web search, reasoning, and research through Perplexity's API
Version	0.6.1
Registry Type	npm
Package Identifier	@perplexity-ai/mcp-server

This enables clients with MCP Registry integration to discover and install the server automatically.

Sources: server.json1-26