Generic MCP Client Integration

This page documents how to connect any MCP-compliant client to the Perplexity MCP server, covering both transport modes (stdio and HTTP) and the session model. It focuses on the protocol-level integration points so you can adapt the configuration to clients not covered by the dedicated guides.

For client-specific configuration, see:

• Claude Desktop and Plugin Marketplace — 6.1
• Cursor and VS Code — 6.2
• Windsurf and Codex — 6.3

For deployment options that affect what endpoint a client connects to, see the Deployment section.

---

Transport Modes

The server supports two MCP transport types. The correct choice depends on how your client communicates:

Transport	When to use	Entry point
stdio	Client launches the server as a child process	src/index.ts via npx
http (Streamable HTTP)	Client connects over HTTP to a running server	src/http.ts at /mcp

The canonical transport declaration is in server.json, which registers the server in the MCP Registry:

server.json1-17

The "type": "stdio" field in that manifest signals to registry consumers that the primary supported transport is stdio. The HTTP transport is an additional deployment mode not declared in the registry manifest.

Sources: server.json1-17 README.md105-107

---

stdio Integration

Transport diagram: stdio mode

Sources: src/index.ts README.md56-78

Command

The server is launched via npx. The minimum required configuration any client must provide:

Field	Value
command	npx
args[0]	-y or -yq
args[1]	@perplexity-ai/mcp-server
env.PERPLEXITY_API_KEY	your API key

The -y flag tells npx to install the package without prompting. The -yq variant additionally suppresses installation progress output to stdout — this is required for strict MCP clients that fail on unexpected stdout bytes before the first MCP message frame. See the Troubleshooting page for details on the EOF / Initialize error this can cause.

Generic mcpServers Configuration Block

Most stdio-mode MCP clients accept a JSON configuration in a mcpServers wrapper:

If your client uses a different top-level wrapper (e.g., VS Code uses "servers" with an explicit "type": "stdio" field), consult its documentation for the key name, but the command, args, and env fields remain the same.

Optional Environment Variables

These can be added to the env block in any stdio configuration:

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

Sources: README.md32-38 README.md56-78

---

HTTP Integration

Transport diagram: HTTP mode

Sources: src/http.ts43-67 src/http.ts69-71

Endpoint

When running in HTTP mode, the server exposes two routes:

Route	Method	Purpose
/mcp	POST, GET	MCP protocol endpoint
/health	GET	Liveness check

The default base URL is http://localhost:8080. Configure the port and bind address with PORT and BIND_ADDRESS environment variables.

To connect an HTTP-capable MCP client, point it at:

http://<host>:<port>/mcp

For example, with default settings: http://localhost:8080/mcp

Sources: src/http.ts43-71 README.md168

Session Handling

The HTTP transport uses StreamableHTTPServerTransport from @modelcontextprotocol/sdk. Each inbound request to /mcp creates a new transport instance:

src/http.ts45-56

Key details:

• sessionIdGenerator: undefined — sessions are stateless; no session ID is assigned or tracked across requests src/http.ts46-47
• The transport is closed when the HTTP response is closed (res.on('close', ...)) src/http.ts50-52
• The server instance (mcpServer) is shared across all requests, created once at startup src/http.ts41

The StreamableHTTPServerTransport exposes Mcp-Session-Id and mcp-protocol-version in CORS response headers, allowing browser-based clients to read them src/http.ts36

Sources: src/http.ts41-56

CORS

The HTTP server applies CORS middleware via the cors npm package. The policy is controlled by the ALLOWED_ORIGINS environment variable:

• Default: ["*"] — all origins permitted
• Comma-separated list: only listed origins are permitted

Allowed request headers: Content-Type, mcp-session-id
Exposed response headers: Mcp-Session-Id, mcp-protocol-version

src/http.ts21-37

Sources: src/http.ts18-37

---

Module Responsibility Map

Which code entity handles each integration concern

Sources: src/index.ts src/http.ts src/server.ts

---

Choosing a Transport

Sources: README.md105-107 README.md177

---

Summary

Concern	stdio	HTTP
Entry point	src/index.ts	src/http.ts
Transport class	StdioServerTransport	StreamableHTTPServerTransport
MCP endpoint	stdin/stdout	POST /mcp
Session state	per-process (one session)	stateless per-request
Startup flag	-y or -yq for npx	PORT, BIND_ADDRESS env vars
CORS	N/A	Controlled by ALLOWED_ORIGINS
Health check	N/A	GET /health
Registry declaration	server.json "type": "stdio"	not declared in registry

Sources: server.json1-17 src/http.ts1-79 src/index.ts README.md141-168