Core Dependencies

This page documents the runtime dependencies required for the Perplexity MCP Server to function in production. These dependencies provide essential functionality for MCP protocol implementation, HTTP communication, validation, and API interaction. For information about development-only dependencies used during building and testing, see Development Tooling. For package metadata and distribution configuration, see Package Metadata.

Overview

The Perplexity MCP Server relies on five core runtime dependencies defined in package.json51-56:

Dependency	Version Constraint	Installed Version	Primary Purpose
@modelcontextprotocol/sdk	^1.21.1	1.25.2	MCP protocol implementation and transport layers
express	^4.21.2	4.22.1	HTTP server framework for remote access
cors	^2.8.5	2.8.5	Cross-origin resource sharing middleware
undici	^6.20.0	6.23.0	High-performance HTTP client for API calls
zod	^3.25.46	3.25.76	Runtime type validation and schema definition

These dependencies work together to enable the dual-transport architecture (STDIO and HTTP), handle communication with the Perplexity AI API, and ensure type safety throughout the application. The installed versions are locked in package-lock.json while the package.json constraints allow compatible updates.

Dependency Import Map

Diagram: Core dependency exports and their usage in source files

Sources: package.json51-56 package-lock.json src/index.ts src/http.ts src/server.ts

@modelcontextprotocol/sdk

The Model Context Protocol SDK is the foundational dependency that provides all MCP-specific functionality. Version ^1.21.1 is specified in package.json52

Key Exports and Usage

Diagram: MCP SDK class instantiation and connection flow

The SDK provides three critical components:

1. Server Class: The core MCP server implementation instantiated in createPerplexityServer() function in src/server.ts This class handles:

   • Tool registration via server.setRequestHandler(ListToolsRequestSchema, ...)
   • Request routing to tool handlers
   • MCP protocol compliance and message formatting
   • Error handling and response serialization

2. StdioServerTransport: Instantiated in src/index.ts as new StdioServerTransport() to create a STDIO-based transport. This transport:

   • Reads MCP protocol messages from process.stdin
   • Writes responses to process.stdout
   • Enables local desktop client integration (Claude Desktop, Cursor, etc.)

3. StreamableHTTPServerTransport: Instantiated in src/http.ts to create HTTP-based transport. This transport:

   • Handles HTTP POST requests at the /mcp endpoint
   • Supports streaming responses via Server-Sent Events (SSE)
   • Enables remote client access over network connections

Protocol Implementation

The SDK enforces MCP protocol compliance by providing typed interfaces for:

• Tool definitions and schemas
• Request/response message formats
• Error handling conventions
• Transport abstraction

The Server class from the SDK handles the protocol-level operations while allowing application-specific tool implementations to be registered via server.setRequestHandler() calls in src/server.ts

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

express

Express is a minimal and flexible Node.js web application framework used exclusively for the HTTP server mode. Version ^4.21.2 is specified in package.json54

HTTP Server Architecture

Diagram: Express HTTP server initialization and middleware stack

Express is imported and configured in src/http.ts where it:

1. Creates application instance: const app = express() initializes the Express application
2. JSON body parsing: app.use(express.json()) middleware parses incoming JSON request bodies
3. CORS configuration: app.use(cors({ origin: allowedOrigins, credentials: true })) enables cross-origin requests
4. MCP endpoint: app.post('/mcp', ...) endpoint receives MCP protocol messages and delegates to StreamableHTTPServerTransport.handleRequest()
5. Health check: app.get('/health', ...) returns { status: 'ok' } for monitoring
6. Server binding: app.listen(PORT, BIND_ADDRESS) starts the HTTP server

The Express server listens on the port specified by PORT environment variable (default: 8080) and binds to the address specified by BIND_ADDRESS (default: 0.0.0.0 for public access, 127.0.0.1 for local-only).

Middleware Stack

The HTTP server uses a minimal middleware stack:

• express.json(): Parses incoming JSON payloads
• cors(): Handles CORS preflight and headers
• Custom /mcp route handler: Delegates to MCP transport

Sources: package.json54 src/http.ts

cors

The CORS package provides Express middleware for handling Cross-Origin Resource Sharing. Version ^2.8.5 is specified in package.json53

CORS Configuration

Diagram: CORS configuration and request handling flow

CORS is configured in src/http.ts with:

• Origin whitelist: Controlled by ALLOWED_ORIGINS environment variable (comma-separated list)
  • If not set: Allows all origins (*)
  • If set: Only specified origins (e.g., https://app1.com,https://app2.com)
• Credentials: credentials: true enables cookies and authorization headers
• Preflight handling: Automatically responds to OPTIONS requests with allowed headers and methods

This configuration enables browser-based MCP clients to access the HTTP server from different domains while maintaining security through configurable origin restrictions. The CORS middleware handles both preflight OPTIONS requests and adds appropriate headers to actual requests.

Sources: package.json53 src/http.ts

undici

Undici is a high-performance HTTP/1.1 client that provides the fetch implementation and proxy support. Version ^6.20.0 is specified in package.json55

Fetch and Proxy Implementation

Diagram: Undici fetch and proxy configuration flow

Undici serves as the HTTP client for all Perplexity API communication in src/server.ts Key features:

1. Fetch API: Provides fetch() implementation compatible with standard Fetch API specification
2. ProxyAgent: Enables HTTP/HTTPS proxy support for corporate network environments
3. Performance: Optimized for high-throughput HTTP/1.1 connections with connection pooling

Proxy Configuration Hierarchy

The getProxyUrl() function in src/server.ts implements a proxy precedence order:

When a proxy URL is detected, ProxyAgent is instantiated and passed to fetch:

Timeout Handling

The proxyAwareFetch() wrapper function implements timeout logic:

• Timeout duration: Controlled by PERPLEXITY_TIMEOUT_MS (default: 600000ms = 10 minutes)
• Cancellation mechanism: Uses AbortController to cancel pending requests
• Cleanup: finally block clears timeout timer to prevent memory leaks
• Error handling: Throws descriptive error on timeout: "Request timed out after {timeout}ms"

This timeout is critical for the sonar-deep-research model which can take 30+ seconds to respond.

Sources: package.json55 src/server.ts

zod

Zod is a TypeScript-first schema validation library used for runtime type checking and validation. Version ^3.25.46 is specified in package.json56

Schema Definition and Validation

Diagram: Zod schema validation pipeline and type inference

Zod is used throughout src/server.ts for runtime validation and type safety:

1. Message Schema Definition:

2. Runtime Validation: The validateMessages() function validates incoming message arrays:

3. Type Inference: z.infer<> utility generates TypeScript types from schemas, ensuring compile-time and runtime type safety are synchronized. This prevents type mismatches between schema validation and function signatures.

Validation Error Handling

When validation fails, Zod provides detailed error messages with:

• Field path: Which field(s) failed validation (e.g., messages[0].role)
• Expected type: What type was expected (e.g., enum ['system', 'user', 'assistant'])
• Received value: What value was actually provided

These errors are caught and wrapped in MCP error responses, ensuring clients receive actionable feedback about malformed requests before they reach the Perplexity API.

Sources: package.json56 src/types.ts src/server.ts

Dependency Version Constraints

All dependencies use caret (^) version ranges, allowing automatic updates to compatible versions:

Diagram: Semantic versioning constraints

The caret range ensures:

• Security patches: Automatically applied (e.g., 4.21.2 → 4.21.3)
• Minor updates: Automatically applied (e.g., 4.21.2 → 4.22.0)
• Major versions: Blocked to prevent breaking changes (e.g., 4.x does not upgrade to 5.x)

This policy balances stability with security, allowing the package manager to apply non-breaking updates during installation while protecting against API changes.

Sources: package.json51-56

Transitive Dependencies

Each core dependency brings its own dependency tree. The most significant transitive dependencies include:

MCP SDK Dependencies

The @modelcontextprotocol/sdk package (v1.25.2) depends on several libraries visible in package-lock.json577-614:

Transitive Dependency	Version	Purpose in MCP SDK
ajv	^8.17.1	JSON Schema validation for tool definitions
ajv-formats	^3.0.1	Additional format validators (email, URL, etc.)
eventsource	^3.0.2	Server-Sent Events for streaming responses
eventsource-parser	^3.0.0	SSE protocol parsing
jose	^6.1.1	JWT/JWE authentication utilities
pkce-challenge	^5.0.0	OAuth PKCE flow support
zod-to-json-schema	^3.25.0	Converts Zod schemas to JSON Schema for MCP protocol
express (nested)	^5.0.1	Used by Hono node adapter
express-rate-limit	^7.5.0	Rate limiting middleware

These transitive dependencies are managed automatically by npm and do not require direct interaction from application code. The MCP SDK internally uses these for protocol features like schema validation, streaming, and authentication.

Express Ecosystem

Express (v4.22.1) brings its middleware ecosystem including package-lock.json2102-2147:

Transitive Dependency	Version	Purpose
body-parser	~1.20.3	JSON/URL-encoded body parsing
cookie	~0.7.1	Cookie serialization
cookie-signature	~1.0.6	Cookie signing
accepts	~1.3.8	Content negotiation
etag	~1.8.1	ETag generation
finalhandler	~1.3.1	Default error handler
serve-static	~1.16.2	Static file serving

These are automatically included and configured by Express.

Undici Dependencies

Undici (v6.23.0) is self-contained with minimal transitive dependencies, which contributes to its performance characteristics. It has no significant sub-dependencies beyond Node.js built-ins.

Sources: package-lock.json577-614 package-lock.json2102-2147

Compatibility Requirements

The dependencies enforce the following compatibility requirements:

Dependency	Node.js Requirement	Notes
@modelcontextprotocol/sdk	>=18	MCP protocol features require modern Node.js
express	>=0.10.0	Broadly compatible, but server uses >=18
cors	>=0.10.0	No specific restrictions
undici	>=18.17	Native fetch requires Node 18.17+
zod	Any	Pure TypeScript, no Node.js dependency

The package enforces Node.js >=18 in package.json68-70 to satisfy the most restrictive requirement (undici's Node 18.17+ requirement for native fetch support).

Sources: package.json68-70 package-lock.json