Windsurf and Codex

This page covers how to configure the @perplexity-ai/mcp-server for the Windsurf IDE and Codex CLI. Both use the stdio transport mode, but each has a different configuration mechanism.

For Cursor and VS Code configuration, see 6.2. For Claude Desktop, see 6.1. For a generic overview of stdio vs HTTP transport, see 6.4.

---

Overview

Both Windsurf and Codex launch the MCP server as a child process over stdio. The server entry point is src/index.ts, which reads PERPLEXITY_API_KEY, constructs a StdioServerTransport, and calls server.connect().

Configuration summary:

Client	Mechanism	Config Location
Windsurf	JSON config file (mcpServers block)	~/.codeium/windsurf/mcp_config.json
Codex	CLI command (codex mcp add)	CLI-managed config

---

Windsurf

Configuration File

Windsurf reads MCP server definitions from ~/.codeium/windsurf/mcp_config.json. The structure is the same mcpServers wrapper used by Cursor and Claude Desktop README.md54-78

Replace your_key_here with a valid Perplexity API key obtained from the API portal.

Config Field Reference

Field	Value	Notes
command	"npx"	Invokes the package runner
args[0]	"-y"	Auto-confirms npx install prompt
args[1]	"@perplexity-ai/mcp-server"	The published npm package
env.PERPLEXITY_API_KEY	Your API key	Required; validated at startup in src/index.ts

Optional Environment Variables

These can be added under the env block:

Variable	Purpose	Default
PERPLEXITY_TIMEOUT_MS	Request timeout in ms	300000 (5 min)
PERPLEXITY_LOG_LEVEL	Log verbosity (DEBUG/INFO/WARN/ERROR)	ERROR
PERPLEXITY_BASE_URL	Override API base URL	https://api.perplexity.ai
PERPLEXITY_PROXY	Outbound HTTPS proxy	None

Strict Client Note

If Windsurf reports initialization errors or EOF during startup, npx may be writing installation progress messages to stdout, which corrupts the MCP framing. Switch to the quieter flag README.md177:

The -q flag suppresses npx output. See 11 for additional troubleshooting.

Sources: README.md54-78

---

Codex

CLI Installation Command

Codex provides a dedicated codex mcp add subcommand that registers an MCP server. The invocation mirrors the claude mcp add pattern README.md99-103:

Command breakdown:

Part	Meaning
codex mcp add perplexity	Registers a server named perplexity
--env PERPLEXITY_API_KEY="your_key_here"	Injects the API key as an environment variable
--	Separator before the server launch command
npx -y @perplexity-ai/mcp-server	The command Codex will spawn via stdio

Codex stores the resulting configuration in its own managed config file; no manual JSON editing is required.

Optional Environment Variables via CLI

Additional environment variables can be appended with repeated --env flags:

Sources: README.md99-103

---

How Both Clients Connect to the Server

The following diagram maps client configuration to the code execution path:

Diagram: stdio connection path for Windsurf and Codex

Sources: README.md54-78 README.md99-103 src/index.ts

---

Diagram: config key-to-code mapping

Sources: README.md54-78 README.md99-103

---

Comparison: Windsurf vs Codex vs Other Clients

Aspect	Windsurf	Codex	Cursor	Claude Desktop
Config mechanism	JSON file	CLI command	JSON file	JSON file
Config file location	~/.codeium/windsurf/mcp_config.json	CLI-managed	~/.cursor/mcp.json	claude_desktop_config.json
JSON wrapper key	mcpServers	N/A	mcpServers	mcpServers
Transport	stdio	stdio	stdio	stdio
-yq quiet flag may be needed	Possibly	Possibly	See 6.2	See 6.1

Sources: README.md54-78 README.md99-103