 |
VOOZH | about |
|
VOOZH | about |
This document details how the @perplexity-ai/mcp-server implements the Model Context Protocol (MCP), including the server manifest specification, SDK usage, and tool registration mechanisms. For information about the dual transport modes (stdio and HTTP), see page 2.2. For details on the four exposed tools, see page 2.3.
The server declares its capabilities and metadata through a standardized server.json manifest file that conforms to the MCP server schema specification.
| Field | Value | Purpose |
|---|---|---|
$schema | MCP server schema URL | Validates manifest structure against official spec |
name | ai.perplexity/mcp-server | Unique identifier following domain/name convention |
title | Perplexity API Platform | Human-readable display name |
description | Brief capability summary | Describes core functionality |
version | 0.8.3 | Semantic version matching package.json |
packages[].registryType | npm | Distribution mechanism |
packages[].identifier | @perplexity-ai/mcp-server | npm package name |
packages[].transport.type | stdio | Primary transport protocol |
Sources: server.json1-17
The server uses the official @modelcontextprotocol/sdk package (v1.25.2) to implement the MCP protocol. The SDK provides the McpServer class and transport layer abstractions.
McpServer construction and tool registration flow
Sources: src/server.ts1 src/index.ts3 src/http.ts5
The createPerplexityServer() factory function instantiates and configures the MCP server with metadata and instructions.
The McpServer constructor takes two arguments: a server identity object and an options object containing the instructions string.
| Parameter | Type | Purpose |
|---|---|---|
name | string | "ai.perplexity/mcp-server" — matches server.json |
version | string | "0.8.3" — synchronized with package.json and server.json |
instructions | string | Natural language tool-selection guidance sent to MCP clients |
The instructions string describes all four tools and their recommended use cases. MCP clients surface this text to help LLMs decide which tool to invoke for a given user request.
Sources: src/server.ts298-313
The server exposes four tools through the MCP protocol using the server.registerTool() method. Each tool registration includes metadata, schemas, and a handler function.
server.registerTool() call sequence inside createPerplexityServer()
Each call to server.registerTool() takes three arguments:
"perplexity_ask")title, description, inputSchema, outputSchema, and annotationsperformChatCompletion() or performSearch(), and returns the MCP response objectSee src/server.ts361-399 for the perplexity_ask registration as a representative example.
All input schemas use Zod for type-safe validation. The messageSchema and shared filter fields are defined once and reused across multiple tool schemas:
Sources: src/server.ts315-359 src/server.ts361-529
The server implements the MCP protocol through several key mechanisms that ensure compatibility with MCP clients.
Each registered tool includes standardized annotations that inform MCP clients about tool behavior:
| Annotation | Value | Meaning |
|---|---|---|
readOnlyHint | true | Tool does not modify state |
openWorldHint | true | Tool accesses live external data (web) |
idempotentHint | false | Repeated identical calls may return different results |
destructiveHint | false | Tool does not delete or mutate any data |
The idempotentHint: false value reflects the live nature of web-grounded results — the same query can return different content over time.
Sources: src/server.ts373-378 src/server.ts412-417 src/server.ts450-455 src/server.ts505-510
The server uses Zod schemas for runtime validation and automatic JSON Schema generation for MCP clients.
Zod schema composition inside createPerplexityServer()
Three input schema variants are composed from shared field definitions and assigned to tools as follows:
| Schema | Used by | Fields |
|---|---|---|
messagesOnlyInputSchema | perplexity_ask | messages, search_recency_filter, search_domain_filter, search_context_size |
messagesWithStripThinkingInputSchema | perplexity_reason | above + strip_thinking |
researchInputSchema | perplexity_research | messages, strip_thinking, reasoning_effort |
perplexity_search uses its own inline schema (searchInputSchema) with query, max_results, max_tokens_per_page, and country fields.
All chat-completion tools share responseOutputSchema (a single response string field). perplexity_search uses searchOutputSchema with a results string field.
Sources: src/server.ts315-359 src/server.ts481-493
Tool handlers return a standardized structure that conforms to MCP protocol requirements:
| Field | Type | Purpose |
|---|---|---|
content | Array | MCP protocol-required content array |
content[].type | "text" | Content type indicator |
content[].text | string | Response text with appended citations |
structuredContent | Object | Typed structured output matching outputSchema |
structuredContent.response | string | Same content as text, for schema-aware clients |
The dual content / structuredContent representation ensures compatibility with MCP clients regardless of whether they prefer unstructured text or schema-validated structured data.
Sources: src/server.ts394-398 src/server.ts432-436 src/server.ts473-478 src/server.ts523-527
The createPerplexityServer() function accepts an optional serviceOrigin parameter that propagates through all API calls for telemetry purposes.
This parameter is included in the X-Service header of Perplexity API requests, enabling the server to track which transport mode (stdio vs HTTP) initiated each request.
Sources: src/server.ts333 src/server.ts427 src/server.ts166-172
Refresh this wiki