perplexity-control-mcp
Provides comprehensive programmatic control over the Perplexity API platform, including Sonar chat completions, deep research, agent API with multi-step reasoning, raw web search, embeddings generation, API key management, cost estimation, and model catalog.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@perplexity-control-mcp search for the latest breakthroughs in nuclear fusion"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@garza-os/perplexity-control-mcp
A comprehensive MCP (Model Context Protocol) server that provides full programmatic control over the Perplexity API platform. Unlike the official Perplexity MCP server (which only exposes search, ask, research, and reason), this server is a complete control plane.
Why this exists
The official Perplexity MCP server wraps only the Sonar chat endpoint and hides the underlying API. This server exposes every Perplexity API surface:
Capability | Official MCP | This server |
Sonar chat completions | ✅ (as | ✅ |
Deep research | ✅ (as | ✅ |
Agent API | ❌ | ✅ |
Raw web search | ❌ | ✅ |
Async jobs | ❌ | ✅ |
Embeddings | ❌ | ✅ |
Contextualized embeddings | ❌ | ✅ |
API key management | ❌ | ✅ |
Cost estimation | ❌ | ✅ |
Model catalog | ❌ | ✅ |
Health check | ❌ | ✅ |
HTTP transport | ❌ | ✅ Streamable HTTP |
Full parameter control | ❌ | ✅ All API params exposed |
Related MCP server: MCP Perplexity Pro
Installation
git clone <repo>
cd perplexity-control-mcp
npm install
cp .env.example .env
# Edit .env and set PERPLEXITY_API_KEY
npm run buildConfiguration
Variable | Default | Description |
| (required) | Your Perplexity API key |
|
|
|
|
| HTTP port (only for |
MCP Client Configuration
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"perplexity-control": {
"command": "node",
"args": ["/absolute/path/to/perplexity-control-mcp/dist/index.js"],
"env": {
"PERPLEXITY_API_KEY": "pplx-your-key-here"
}
}
}
}Cursor
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"perplexity-control": {
"command": "node",
"args": ["/absolute/path/to/perplexity-control-mcp/dist/index.js"],
"env": {
"PERPLEXITY_API_KEY": "pplx-your-key-here"
}
}
}
}Comet (HTTP transport)
Start the server in HTTP mode:
MCP_TRANSPORT=http MCP_PORT=3001 PERPLEXITY_API_KEY=pplx-... npm startThen configure Comet to use http://localhost:3001/mcp.
npx (without cloning)
After publishing to npm:
{
"mcpServers": {
"perplexity-control": {
"command": "npx",
"args": ["-y", "@garza-os/perplexity-control-mcp"],
"env": {
"PERPLEXITY_API_KEY": "pplx-your-key-here"
}
}
}
}All Tools
Agent API
agent_create
Create an agent response using the Perplexity Agent API (POST /v1/agent). Supports multi-step agentic reasoning with tool use.
Parameter | Type | Required | Description |
| string | message[] | ✅ | User input (string or messages array) |
| string | * | Provider/model format, e.g. |
| string[] | * | Fallback model chain (max 5). Overrides |
| enum | * |
|
| string | System instructions | |
| array |
| |
| integer | Maximum response tokens | |
| integer (1-10) | Maximum agentic steps | |
| object | `{effort: "low" | |
| object | Structured output: | |
| string | ISO 639-1 code, e.g. |
*One of model, models, or preset is required.
Sonar API
sonar_chat
Chat completions with live web grounding (POST /v1/sonar).
Parameter | Type | Description |
| enum |
|
| message[] | Conversation messages with |
| integer | Max response tokens |
| float (0-2) | Sampling temperature |
| float (0-1) | Nucleus sampling probability |
| string[] | Whitelist/blacklist domains (prefix |
| enum |
|
| boolean | Include image results |
| string | ISO 8601 date |
| string | ISO 8601 date |
| object |
|
| string | BCP 47 language tag |
sonar_async_submit
Submit an async deep research job (POST /v1/async/sonar). Same parameters as sonar_chat. Returns a request_id.
sonar_async_get
Poll an async job (GET /v1/async/sonar/{request_id}).
Parameter | Type | Description |
| string | ID from |
sonar_async_list
List all async jobs (GET /v1/async/sonar). No parameters.
Search API
web_search
Raw web search returning full page content (POST /search).
Parameter | Type | Description |
| string | string[] | Query or up to 5 queries |
| integer (1-20) | Results per query (default 5) |
| integer (≤1M) | Total token budget |
| integer | Per-page token limit (default 4096) |
| string[] (≤20) | Domain include/exclude list |
| string[] (≤10) | BCP 47 language filter |
| enum |
|
| string | ISO 8601 date |
| string | ISO 8601 date |
| string | ISO 8601 date |
| string | ISO 8601 date |
| string | ISO 3166-1 alpha-2 country code |
| enum |
|
Embeddings API
embeddings_create
Generate dense vector embeddings (POST /v1/embeddings).
Parameter | Type | Description |
| string | string[] | Text to embed |
| enum |
|
| integer (128-2560) | Output vector dimensions |
| enum |
|
embeddings_contextualized
Document-aware embeddings where each chunk's vector is influenced by surrounding context (POST /v1/contextualizedembeddings).
Parameter | Type | Description |
| string[][] | Array of documents, each being an array of chunks |
| enum |
|
| integer (128-2560) | Output vector dimensions |
| enum |
|
API Key Management
api_key_generate
Generate a new API key (POST /generate_auth_token).
Parameter | Type | Description |
| string | Optional label for the key |
Returns: { auth_token, created_at_epoch_seconds, token_name }
api_key_revoke
Revoke an API key (POST /revoke_auth_token). Irreversible.
Parameter | Type | Description |
| string | The key to revoke |
api_key_rotate
Convenience: generates a new key, tests it, then revokes the current key.
Parameter | Type | Description |
| string | Optional label for the new key |
Returns: { new_key, old_key_revoked, note }
Save the new_key immediately and update PERPLEXITY_API_KEY in your environment.
Utility Tools
estimate_cost
Calculate estimated USD cost before sending a request.
Parameter | Type | Description |
| string | Model ID |
| integer | Input token count |
| integer | Output token count |
| object |
|
list_models
Returns the full model catalog with descriptions, context lengths, and pricing.
health_check
Verifies API connectivity and key validity. Makes a minimal test request and returns latency and rate limit information.
Architecture
perplexity-control-mcp/
├── src/
│ ├── index.ts # Entry point — stdio or HTTP transport
│ ├── config/
│ │ └── index.ts # Env var validation (Zod)
│ ├── services/
│ │ └── perplexity-client.ts # Centralized HTTP client
│ └── tools/
│ ├── index.ts # Tool registry + request routing
│ ├── agent-tools.ts # agent_create
│ ├── sonar-tools.ts # sonar_chat, sonar_async_*
│ ├── search-tools.ts # web_search
│ ├── embeddings-tools.ts # embeddings_create, embeddings_contextualized
│ ├── admin-tools.ts # api_key_generate/revoke/rotate
│ └── utility-tools.ts # estimate_cost, list_models, health_check
├── .env.example
├── package.json
└── tsconfig.jsonClient features
Automatic
Authorization: Bearertoken injectionStructured error responses with HTTP status codes
Rate limit header parsing (
X-RateLimit-Remaining,X-RateLimit-Reset,X-RateLimit-Limit)Automatic cost calculation from response
usageobjectsRequest logging to stderr
Transport
stdio (default): Pipe-based transport for local MCP clients
http: Stateful Streamable HTTP transport with per-session server instances. Each session gets its own
Serverinstance. Sessions are cleaned up on disconnect.
Development
# Watch mode
npm run dev
# Build
npm run build
# Run (stdio)
PERPLEXITY_API_KEY=pplx-... npm start
# Run (HTTP)
MCP_TRANSPORT=http PERPLEXITY_API_KEY=pplx-... npm startLicense
MIT
Available Tools
14 toolsagent_createA
Create an agent response using the Perplexity Agent API (POST /v1/agent). Supports multi-step agentic reasoning with web search, URL fetching, and custom function tools. Either model, models, or preset must be provided.
Inputs: input (required), model, tools, models, +7 more.
api_key_generateA
Generate a new Perplexity API key (POST /generate_auth_token). Returns the new auth_token, creation timestamp, and optional token_name. Note: This uses the PERPLEXITY_API_KEY set in your environment to authenticate.
Inputs: token_name.
api_key_revokeA
Revoke an existing Perplexity API key (POST /revoke_auth_token). The revoked key will immediately stop working. This action is irreversible.
Inputs: auth_token (required).
api_key_rotateA
Rotate the current API key: generates a new key, verifies it works by making a test request, then revokes the old key. Returns the new key and rotation status. IMPORTANT: Save the new key immediately — it will not be shown again.
Inputs: token_name.
embeddings_contextualizedA
Generate context-aware embeddings for document chunks (POST /v1/contextualizedembeddings). Unlike standard embeddings, each chunk's vector is influenced by surrounding chunks in the same document, producing better representations for RAG. Input is an array of arrays: each inner array is a document's chunks.
Inputs: input (required), model, dimensions, encoding_format.
embeddings_createA
Generate dense vector embeddings for one or more text strings (POST /v1/embeddings). Use for semantic search, similarity comparison, or retrieval-augmented generation (RAG). Returns vectors in base64 format.
Inputs: input (required), model, dimensions, encoding_format.
estimate_costA
Estimate the USD cost of a request before sending it. Returns a breakdown by input tokens, output tokens, and tool invocations.
Inputs: model (required), input_tokens (required), output_tokens, tool_invocations.
health_checkA
Test API connectivity and verify the configured PERPLEXITY_API_KEY is valid and working. Makes a minimal test request to the Sonar API.
Inputs: no named parameters.
list_modelsA
List all available Perplexity models with descriptions, context lengths, and current pricing. Prices are in USD per million tokens.
Inputs: no named parameters.
sonar_async_getA
Get the status or result of an async Sonar job (GET /v1/async/sonar/{request_id}).
Inputs: request_id (required).
sonar_async_listA
List all async Sonar jobs (GET /v1/async/sonar).
Inputs: no named parameters.
sonar_async_submitA
Submit an asynchronous deep research job (POST /v1/async/sonar). Returns a request_id to poll with sonar_async_get. Ideal for sonar-deep-research model.
Inputs: messages (required), model, top_p, max_tokens, +8 more.
sonar_chatA
Chat completions with live web grounding using Perplexity Sonar models (POST /v1/sonar). Supports domain filters, recency filters, and location-aware search.
Inputs: messages (required), model, top_p, max_tokens, +8 more.
web_searchA
Perform a raw web search returning full page content (POST /search). Returns structured result objects with URL, title, and text content. Supports up to 5 parallel queries, domain filters, date filters, and specialized academic/SEC modes.
Inputs: query (required), country, max_tokens, max_results, +9 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Several tools have overlapping functionality: sonar_chat, agent_create, and web_search all involve web-searching capabilities, which could confuse an agent. However, the descriptions clearly delineate their use cases, and the async sonar tools are distinct. Overall, some ambiguity remains but descriptions mitigate it.
Tool names are inconsistent in their verb/noun ordering. Some use verb_noun (list_models, estimate_cost), while others use noun_verb (api_key_generate, web_search, sonar_chat). There are consistent sub-patterns like sonar_async_* and api_key_*, but no unified convention across the set.
14 tools is well within the ideal range for a server covering Perplexity's API surface. Each tool addresses a distinct feature area such as API key management, embeddings, search, async jobs, and cost estimation, without feeling bloated or sparse.
The tool set covers core workflows for search, chat, embeddings, and API key management, but notable gaps exist. There is no way to cancel an async Sonar job, list existing API keys, or list/delete agents. These missing lifecycle operations could cause agent failures in certain management scenarios.
Related MCP Connectors
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for AI dialogue using various LLM models via AceDataCloud
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP Server for the Perplexity API.39 PyPI66MIT
- AlicenseAqualityBmaintenanceA comprehensive MCP server that provides intelligent access to Perplexity AI's search and reasoning models with automatic model selection, conversation management, and project-aware storage. Supports real-time search, deep research, chat sessions, and async operations for complex queries.1122 PyPI3MIT
- AlicenseAqualityCmaintenanceOfficial MCP server for the Perplexity API Platform, enabling AI assistants to perform real-time web search, reasoning, and deep research using Sonar models.455,781 npmMIT
- FlicenseBqualityDmaintenanceUnofficial MCP server that wraps the Perplexity AI web API via browser cookies, enabling search, research, reasoning, and ask tools through STDIO.4-