Local STDIO Deployment

This document describes how to deploy the Perplexity MCP Server locally using the STDIO (Standard Input/Output) transport mechanism. STDIO deployment is the primary mode for individual developer workflows, where MCP clients spawn the server as a subprocess and communicate through standard input/output streams.

For HTTP-based cloud deployments, see HTTP Server Deployment. For Docker containerization, see Docker Deployment. For general configuration options, see Environment Variables Reference.

---

STDIO Transport Architecture

STDIO deployment uses a process-based isolation model where each MCP client spawns an independent instance of the server as a child process. Communication occurs through standard UNIX pipes (stdin/stdout), with the Model Context Protocol messages serialized as JSON-RPC over these streams.

Transport Flow Diagram

STDIO entry point to transport binding (src/index.ts)

Sources: src/index.ts1-27 package.json26-29

Key Components

Component	Code Entity	Purpose
Entry Point	dist/index.js	Executable entry point with shebang #!/usr/bin/env node
Main Function	main() src/index.ts12-21	Initializes transport and connects server
Transport Layer	StdioServerTransport src/index.ts3	MCP SDK transport handling stdin/stdout communication
Server Factory	createPerplexityServer("local-mcp") src/index.ts14	Creates configured McpServer instance
Environment Validation	src/index.ts6-10	Validates PERPLEXITY_API_KEY before startup

Sources: src/index.ts1-27 package.json26-29

---

NPX Execution Mechanism

The server is distributed as an npm package and executed via npx, which handles package resolution, download, caching, and execution without requiring global installation.

Package Resolution Flow

Sources: README.md43-103 package.json1-71

NPX Arguments

Argument	Purpose	Example
-y	Skip confirmation prompt (auto-yes)	npx -y @perplexity-ai/mcp-server
-yq	Skip confirmation and suppress output	npx -yq @perplexity-ai/mcp-server
Package spec	Identifies the package to execute	@perplexity-ai/mcp-server or @perplexity-ai/mcp-server@0.6.2

The -yq flag is recommended for strict MCP clients that fail on unexpected stdout content during initialization. Standard npx -y may write package installation messages to stdout, causing protocol violations.

Sources: README.md177 package.json2-3

---

Subprocess Spawning and Lifecycle

Process Lifecycle

Server subprocess state machine — src/index.ts

State	Code Location	Detail
Validation	src/index.ts6-10	Reads process.env.PERPLEXITY_API_KEY; calls process.exit(1) if absent
Connected	src/index.ts15-16	new StdioServerTransport() then server.connect(transport)
Failed	src/index.ts7-9	console.error(...) then process.exit(1)
Executing	src/server.ts	Tool handler dispatches to performChatCompletion or performSearch

Sources: src/index.ts6-21

Process Characteristics

• Process Isolation: Each MCP client spawns an independent server process
• Lifecycle: Tied to client lifecycle; terminates when client closes connection
• Environment Inheritance: Inherits environment variables from parent process
• Stream Ownership: Exclusive ownership of stdin/stdout for MCP protocol

The subprocess model ensures:

1. Process-level isolation between different clients
2. Automatic resource cleanup when client disconnects
3. Independent configuration per client instance

Sources: src/index.ts1-27

Entry Point Implementation

The entry point src/index.ts1-27 implements a minimal bootstrap:

1. Shebang src/index.ts1: #!/usr/bin/env node — enables direct execution from the bin field in package.json
2. Environment guard src/index.ts6-10: Reads process.env.PERPLEXITY_API_KEY; exits immediately with code 1 if absent
3. Server factory src/index.ts14: createPerplexityServer("local-mcp") — the string "local-mcp" identifies this as the STDIO deployment context
4. Transport src/index.ts15: new StdioServerTransport() — wraps process.stdin / process.stdout
5. Connect src/index.ts16: await server.connect(transport) — starts the MCP protocol handshake
6. Error boundaries src/index.ts17-25: Two catch sites — inner try/catch in main() and outer .catch() on the main() call — both log and call process.exit(1)

Sources: src/index.ts1-27

---

Client Configuration Patterns

Different MCP clients use varying configuration formats to spawn the STDIO server. All configurations share the same core pattern: execute npx with the package identifier and provide environment variables.

Universal Configuration Structure

JSON config fields that control subprocess spawning

Sources: README.md40-107

Configuration by Client

mcpServers Format (Cursor, Claude Desktop, Windsurf)

These clients use the mcpServers wrapper format in their respective config files:

Client	Configuration Path
Cursor	~/.cursor/mcp.json
Claude Desktop	claude_desktop_config.json
Windsurf	~/.codeium/windsurf/mcp_config.json

See README.md54-78 for the config block. The command/args/env fields are passed directly to the subprocess spawner.

Sources: README.md54-78

VS Code Format (.vscode/mcp.json)

VS Code uses a servers wrapper with an explicit "type": "stdio" field. See README.md80-97 for the config block. The type field distinguishes this from VS Code's HTTP transport configuration.

Sources: README.md80-97

CLI-Based Installation (Claude Code, Codex)

Some clients provide CLI commands that write the equivalent JSON config automatically:

• Claude Code: claude mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server
• Codex: codex mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server

Sources: README.md40-103

---

Environment Variable Configuration

Required Variables

Variable	Purpose	Validation
PERPLEXITY_API_KEY	Bearer token for Perplexity API auth	Checked at src/index.ts6-10; process.exit(1) if absent

Optional Variables

Variable	Purpose	Default	Notes
PERPLEXITY_TIMEOUT_MS	API request timeout (ms)	300000 (5 min)	Raise to 600000 for perplexity_research
PERPLEXITY_BASE_URL	Custom API base URL	https://api.perplexity.ai	Override for testing or proxies
PERPLEXITY_LOG_LEVEL	Log verbosity	ERROR	DEBUG, INFO, WARN, ERROR — stderr only
PERPLEXITY_PROXY	Proxy URL (highest priority)	None	https://proxy.corp.com:8080
HTTPS_PROXY	Standard HTTPS proxy	None	Used if PERPLEXITY_PROXY is unset
HTTP_PROXY	Standard HTTP proxy (lowest priority)	None	Used if neither above is set

Sources: README.md30-139 src/index.ts6-10

Environment Inheritance Pattern

How PERPLEXITY_API_KEY reaches src/index.ts

Sources: README.md66-96 src/index.ts6-10

---

STDIO-Specific Considerations

Stream Isolation

The STDIO transport uses process streams for MCP communication:

• stdin: Client → Server JSON-RPC requests
• stdout: Server → Client JSON-RPC responses
• stderr: Logging and error messages (not used for protocol)

The StdioServerTransport from the MCP SDK handles protocol serialization and deserialization. Any content written to stdout outside the transport causes protocol violations.

Sources: src/index.ts15-16

NPX Output Pollution

NPX may write installation progress messages to stdout when first downloading a package. This violates the MCP protocol, causing initialization failures in strict clients.

Mitigation strategies:

1. Use npx -yq instead of npx -y to suppress stdout messages
2. Pre-cache the package: npx -y @perplexity-ai/mcp-server (run once manually)
3. Use specific version pins to avoid repeated downloads: npx -y @perplexity-ai/mcp-server@0.6.2

Sources: README.md177

Process Exit Behavior

The server exits with status code 1 in two scenarios:

1. Missing PERPLEXITY_API_KEY (detected at startup)
2. Fatal error during server operation

Exit code 0 indicates clean shutdown triggered by client disconnect.

Sources: src/index.ts6-25

---

Deployment Workflow Diagram

End-to-end path from developer config to running StdioServerTransport

Sources: README.md40-107 src/index.ts1-27 package.json1-71

---

Advantages and Limitations

Advantages of STDIO Deployment

Advantage	Detail
Process isolation	Each client spawns an independent server process; no shared state
Zero server config	No PORT, BIND_ADDRESS, ALLOWED_ORIGINS, or CORS to configure
Automatic lifecycle	Server terminates when client closes; no orphan processes
No installation step	npx resolves and runs the package without npm install -g
No network exposure	Communication is limited to the parent–child pipe; no open ports

Limitations

Limitation	Detail
Single client per process	StdioServerTransport binds exclusively to one stdin/stdout pair
No remote access	Client and server must be co-located on the same machine
Resource overhead	N clients → N server processes (each loads Node.js + dependencies)
stdout must stay clean	Any write to stdout outside StdioServerTransport corrupts the protocol

For multi-client or remote scenarios, see HTTP Server Deployment.

Sources: README.md140-168 src/index.ts1-27

---

Troubleshooting

Issue	Symptom	Solution
API Key Missing	Error: PERPLEXITY_API_KEY environment variable is required	Set PERPLEXITY_API_KEY in client configuration env block
EOF/Initialize Errors	Client fails during initialization	Use npx -yq instead of npx -y to suppress stdout messages
Tool Not Found	Client cannot invoke tools	Verify package name is @perplexity-ai/mcp-server (not @perplexityai/mcp-server)
Proxy Connection Failure	Timeout errors behind corporate proxy	Set PERPLEXITY_PROXY environment variable with proxy URL
Process Hangs	Server doesn't respond	Check client logs; may indicate stdin/stdout stream issue

For general troubleshooting, see Troubleshooting. For proxy configuration details, see Proxy Configuration.

Sources: README.md170-178