HTTP Server Deployment

This page covers running the Perplexity MCP server as a persistent HTTP service using src/http.ts. It documents the Express application structure, endpoint behavior, CORS configuration, per-request transport lifecycle, and all relevant environment variables.

For running the server over stdio (for local IDE integrations), see Local STDIO Deployment. For Docker packaging, see Docker Deployment. For a comparison of the two deployment modes, see Dual Deployment Architecture.

---

Overview

HTTP mode is appropriate when the MCP server needs to be shared across multiple clients, deployed in a container, or accessed over a network. Instead of StdioServerTransport, it uses StreamableHTTPServerTransport from @modelcontextprotocol/sdk.

The entry point is src/http.ts, which creates an Express application exposing two routes: /mcp for MCP protocol traffic and /health for liveness checks.

Sources: src/http.ts1-79

---

Starting the Server

After building the project, the HTTP server is started with:

Or, using the public convenience alias (which binds to all interfaces):

Both scripts invoke src/http.ts as the entry point.

Prerequisite: PERPLEXITY_API_KEY must be set in the environment before starting. The process will call process.exit(1) immediately if it is missing.

Sources: src/http.ts9-13 README.md161-168

---

Environment Variables

All HTTP-mode configuration is controlled by environment variables. The table below lists all variables consumed by src/http.ts, with their defaults.

Variable	Read in src/http.ts	Default	Description
PERPLEXITY_API_KEY	Line 9	(required)	Perplexity API Bearer token. Missing value terminates the process.
PORT	Line 16	8080	TCP port the Express server binds to.
BIND_ADDRESS	Line 17	0.0.0.0	Network interface to bind to. Use 127.0.0.1 to restrict to localhost.
ALLOWED_ORIGINS	Line 18	*	Comma-separated list of allowed CORS origins, or * to allow all.

Additional variables (PERPLEXITY_BASE_URL, PERPLEXITY_TIMEOUT_MS, PERPLEXITY_PROXY, etc.) are consumed by src/server.ts and apply in both modes. See Environment Variables Reference for the full list.

Sources: src/http.ts9-18 README.md146-152

---

Endpoints

The Express application registers two routes.

POST /mcp (and all methods)

The /mcp route is registered with app.all, meaning it accepts GET, POST, DELETE, and any other HTTP method. This is required by the MCP Streamable HTTP transport specification, which uses different methods for different protocol operations.

Successful response: Determined by StreamableHTTPServerTransport with enableJsonResponse: true.

Error response (unhandled exception):

GET /health

A simple liveness endpoint, used by load balancers and container orchestrators.

Response:

Sources: src/http.ts43-71

---

Per-Request Transport Lifecycle

A key design decision in src/http.ts is that createPerplexityServer() is called once at module load time, creating a single shared mcpServer instance. However, a new StreamableHTTPServerTransport is instantiated on every request.

The following diagram maps this flow to code entities:

Diagram: Per-Request Transport Lifecycle in src/http.ts

Notable transport configuration:

• sessionIdGenerator: undefined — disables session management; each request is stateless
• enableJsonResponse: true — responses are sent as JSON (as opposed to SSE streams for this transport layer)

Sources: src/http.ts41-66

---

CORS Configuration

CORS is handled by the cors npm package, configured with a custom origin callback. The logic in src/http.ts is as follows:

Diagram: CORS Origin Resolution Logic

The cors middleware also configures the following headers to support browser-based MCP clients:

CORS Option	Value	Purpose
exposedHeaders	Mcp-Session-Id, mcp-protocol-version	Allows browser JS to read MCP-specific response headers
allowedHeaders	Content-Type, mcp-session-id	Allows browser JS to send MCP-specific request headers

Configuring ALLOWED_ORIGINS:

Sources: src/http.ts18-37

---

Module Dependency Map

Diagram: src/http.ts Imports and Their Roles

src/http.ts does not import from src/types.ts, src/validation.ts, or src/index.ts. All MCP tool logic is encapsulated in src/server.ts.

Sources: src/http.ts1-7

---

Startup and Error Handling

On startup, src/http.ts performs two guards:

1. API key check (src/http.ts9-13): If PERPLEXITY_API_KEY is not set, logger.error is called and process.exit(1) terminates the process before the server starts.

2. Server bind error (src/http.ts76-79): If app.listen emits an error event (e.g., port already in use), logger.error is called and process.exit(1) terminates the process.

During request handling, any uncaught exception inside the /mcp handler logs the error and, if headers have not yet been sent, returns a JSON-RPC 2.0 internal error response.

Sources: src/http.ts9-13 src/http.ts57-66 src/http.ts73-79

---

Connecting a Client

Once the server is running, the MCP endpoint is reachable at:

http://<BIND_ADDRESS>:<PORT>/mcp

With defaults, this is:

http://localhost:8080/mcp

For generic MCP client configuration in HTTP mode, see Generic MCP Client Integration. For the Smithery container deployment, smithery.yaml declares startCommand.type: "http" which points to this HTTP entry point.

Sources: README.md168 smithery.yaml1-16