Server Configuration Files

This page documents the three declarative configuration files that define how the @perplexity-ai/mcp-server package registers itself with external systems: the MCP Registry (server.json), the Claude plugin marketplace (.claude-plugin/marketplace.json), and the Smithery container platform (smithery.yaml). These files are consumed by external tooling and registries — they do not affect the server's runtime behavior directly.

• For runtime environment variables (PERPLEXITY_API_KEY, PERPLEXITY_TIMEOUT_MS, etc.), see Environment Variables Reference.
• For proxy configuration, see Proxy Configuration.
• For how clients use these files to launch the server, see Client Integration.
• For the CI/CD workflows that publish these manifests, see MCP Registry Publishing Workflow and Plugin Validation Workflow.

---

Overview: Three Configuration Files

File-to-Registry Mapping

Sources: server.json1-17 .claude-plugin/marketplace.json1-48 smithery.yaml1-16

File	Consumed By	Purpose
server.json	MCP Registry / mcp-publisher	Registers the package on the MCP server registry
.claude-plugin/marketplace.json	Claude CLI / Claude Plugin Marketplace	Enables one-click install through Claude's plugin marketplace
smithery.yaml	Smithery platform	Declares container runtime and config schema for cloud deployment

---

server.json — MCP Registry Manifest

server.json is the manifest read by the mcp-publisher tool during the MCP Registry Publishing Workflow. It conforms to the schema at https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json.

Field breakdown:

server.json1-17

Field	Value	Description
$schema	https://static.modelcontextprotocol.io/schemas/...	JSON Schema URI for validation
name	ai.perplexity/mcp-server	Namespaced server identifier on the MCP registry
title	Perplexity API Platform	Human-readable display name
description	"Real-time web search..."	Short description shown in registry listings
version	0.8.3	Must match package.json version
packages[0].registryType	npm	Package registry where the server is distributed
packages[0].identifier	@perplexity-ai/mcp-server	npm package identifier
packages[0].version	0.8.3	Package version on npm
packages[0].transport.type	stdio	Declares that this server communicates over stdio

The transport.type: "stdio" field tells MCP clients that they must launch this server as a subprocess and communicate via stdin/stdout. This corresponds directly to the StdioServerTransport used in src/index.ts.

server.json structure

Sources: server.json1-17

---

.claude-plugin/marketplace.json — Claude Plugin Manifest

.claude-plugin/marketplace.json is read by the claude CLI during the Plugin Validation Workflow and published to the Claude plugin marketplace. It has two levels of nesting: a top-level package manifest and a plugins array containing one or more plugin entries.

.claude-plugin/marketplace.json1-48

Top-Level Fields

Field	Value	Description
name	perplexity-mcp-server	Package identifier
owner.name	Perplexity AI	Organization name
owner.email	api@perplexity.ai	Contact email
metadata.description	"Official Perplexity AI plugin..."	Package-level description
metadata.version	0.8.3	Package version

plugins[0] Entry Fields

Field	Value	Description
name	perplexity	Plugin identifier (used as key in mcpServers)
source	./	Relative path to plugin root
description	"Real-time web search..."	Plugin description
version	0.8.3	Plugin version
homepage	https://docs.perplexity.ai/guides/mcp-server	Documentation URL
repository	https://github.com/perplexityai/modelcontextprotocol	Source repository
license	MIT	SPDX license identifier
keywords	["mcp", "search", "web-search", ...]	Searchability tags
category	productivity	Marketplace category
strict	false	Allows the server to use tools not declared in the manifest

The mcpServers Block

The mcpServers block is the most operationally significant part of the manifest. It tells the Claude client exactly how to launch the server:

.claude-plugin/marketplace.json35-45

Sources: .claude-plugin/marketplace.json35-45

Key points about the mcpServers block:

• type: "stdio" — matches the StdioServerTransport transport used by src/index.ts.
• command: "npx" with args: ["-y", "@perplexity-ai/mcp-server"] — launches the package without requiring a manual install step.
• PERPLEXITY_API_KEY is injected from the host environment using shell variable substitution (${PERPLEXITY_API_KEY}).
• PERPLEXITY_TIMEOUT_MS defaults to 600000 ms (10 minutes) using the ${VAR:-default} syntax — this is notably higher than the global default of 300,000 ms (5 minutes) to accommodate sonar-deep-research latency. See Environment Variables Reference for details.

---

smithery.yaml — Container Deployment Spec

smithery.yaml is read by the Smithery platform to deploy the server as a managed container. It references the project's Dockerfile for the build stage and declares the configSchema that Smithery presents to users when configuring the deployment.

smithery.yaml1-16

Field	Value	Description
runtime	container	Instructs Smithery to build and run a Docker image
build.dockerfile	Dockerfile	Path to the Dockerfile relative to repo root
build.dockerBuildPath	.	Docker build context (repo root)
startCommand.type	http	Server is started in HTTP mode (not stdio) inside the container
configSchema.type	object	JSON Schema type for config validation
configSchema.required	["PERPLEXITY_API_KEY"]	Variables that must be provided before deployment

configSchema Properties

Property	Type	Description
PERPLEXITY_API_KEY	string	API key from https://www.perplexity.ai/settings/api
PERPLEXITY_TIMEOUT_MS	string	Request timeout in milliseconds (default 300000)

The startCommand.type: "http" value tells Smithery to use the HTTP server entry point (src/http.ts) rather than the stdio entry point. This aligns with the container-based Docker Deployment mode described elsewhere.

smithery.yaml deployment flow

Sources: smithery.yaml1-16 src/http.ts1-79

---

Version Synchronization

All three files carry an explicit version field. These must stay in sync with the version field in package.json. The NPM Publishing Workflow and MCP Registry Publishing Workflow are both triggered on changes to package.json, providing a coupling point to catch version drift.

File	Version Field Location
server.json	version (top-level) and packages[0].version
.claude-plugin/marketplace.json	metadata.version and plugins[0].version
smithery.yaml	Not versioned — inherits from the built image
package.json	version (source of truth)

Sources: server.json6-16 .claude-plugin/marketplace.json9-18 smithery.yaml1-16