Deployment

This page introduces the deployment options available for @perplexity-ai/mcp-server and helps you choose the right mode for your use case. It covers the entry points, required environment, and the differences between each deployment method at a high level. For detailed configuration variables, see Configuration. For connecting specific clients to a running server, see Client Integration.

---

Overview

The server supports two runtime modes, each with its own entry point and transport:

Mode	Entry Point	Transport Class	Typical Use
stdio	src/index.ts	StdioServerTransport	Local AI client (Cursor, Claude Desktop, VS Code, Codex)
HTTP	src/http.ts	StreamableHTTPServerTransport	Cloud deployments, shared infrastructure, Docker containers

Both modes call the same createPerplexityServer() function in src/server.ts and differ only in how they accept and frame MCP messages. Neither mode requires building the project from source when using npx.

Diagram: Deployment Mode Entry Points

Sources: README.md140-168 src/index.ts src/http.ts

---

Deployment Mode Comparison

Sources: README.md140-168 src/index.ts src/http.ts

---

Required Configuration

All deployment modes share one required environment variable:

Variable	Required	Default	Purpose
PERPLEXITY_API_KEY	Yes	—	Bearer token for all Perplexity API requests
PERPLEXITY_BASE_URL	No	https://api.perplexity.ai	Override the API base URL
PERPLEXITY_TIMEOUT_MS	No	300000 (5 min)	Request timeout in milliseconds
PERPLEXITY_LOG_LEVEL	No	ERROR	DEBUG / INFO / WARN / ERROR

HTTP mode additionally accepts PORT, BIND_ADDRESS, and ALLOWED_ORIGINS. See Environment Variables Reference.

---

Deployment Options

Local STDIO Deployment

The simplest deployment path. The MCP client (e.g., Cursor) spawns the server as a child process and communicates over stdin/stdout. No network port is opened.

• Entry point: src/index.ts, transport: StdioServerTransport
• Invoked via npx @perplexity-ai/mcp-server (or npx -yq for strict clients)
• PERPLEXITY_API_KEY must be available in the process environment

HTTP Server Deployment

Runs as a persistent HTTP service. Clients connect via POST /mcp. Suitable for shared or remote deployments.

• Entry point: src/http.ts, transport: StreamableHTTPServerTransport
• Invoked via npm run start:http
• Exposes POST /mcp and GET /health on the configured PORT (default 8080)
• CORS is controlled by ALLOWED_ORIGINS

Docker Deployment

Packages the HTTP server in a container image. Uses the multi-stage Dockerfile in the repository root.

docker build -t perplexity-mcp-server .
docker run -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server

The server is then reachable at http://localhost:8080/mcp.

Sources: README.md154-168

MCP Registry Publication

Publishes the server to the MCP Registry using the mcp-publisher tool, driven by the server.json manifest. This is handled automatically by the .github/workflows/publish-mcp.yml CI workflow when server.json or package.json changes on main. See CI/CD and Publishing for the full workflow documentation.

---

CI/CD Integration

The publish workflows automate two distribution channels:

Workflow	Trigger	Output
.github/workflows/publish.yml	package.json changed on main	@perplexity-ai/mcp-server on npm
.github/workflows/publish-mcp.yml	server.json or package.json changed on main	Entry in MCP Registry

End-users consuming from npm do not need to build the project; npx handles installation automatically.

Sources: README.md1-10 .github/workflows/publish.yml .github/workflows/publish-mcp.yml