Perplexity's Official MCP Server: Remote Endpoint or Local npx Install

What the Perplexity MCP Server Actually Adds to a Client

A stock coding assistant knows what was in its training data and whatever files you paste into the context window. It cannot go and read a page published this morning. The Perplexity API Platform MCP server exists to close that gap: it exposes Perplexity's Agent API and Search API as MCP tools, so a client that already speaks the Model Context Protocol can call out for real-time web search, reasoning and research without any custom glue code. The intended audience is narrow and specific. You need an MCP-capable client (Cursor, VS Code, Claude Code, Claude Desktop, Codex, Kiro, Windsurf), and you need a Perplexity API key from the API Portal, because every call is billed against that key. If your client has no MCP support, this project does nothing for you. The repository is the official implementation, published as @perplexity-ai/mcp-server on npm under the MIT licence.

Remote Endpoint First, Local Process Second

The README makes a clear recommendation before it shows any code: the remote MCP server is hosted by Perplexity and is described as the easiest way to get started, with the same tools and nothing to install or update. Your client connects over Streamable HTTP to https://api.perplexity.ai/mcp and authenticates with a bearer token. That is the whole architecture on the hosted path: no Node process on your machine, no version drift, no build step. The local path is a Node package. Its bin entry is perplexity-mcp pointing at dist/index.js, with a separate dist/http.js entry for HTTP mode, and it depends on @modelcontextprotocol/sdk, express and cors. The README frames the local server as the fallback for clients that do not support remote servers yet. That ordering matters when you are deciding what to deploy: the hosted endpoint is the default, and the npm package is the escape hatch.

Installing the Local Server and Making a First Call

The fastest local setup is to let the client launch the package through npx, which pulls @perplexity-ai/mcp-server on demand and passes your key through an environment variable. For Claude Code the README gives this command, where you replace the placeholder with the key from the API Portal:

claude mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server

Codex uses the same shape with a different subcommand:

codex mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server

For clients configured by file rather than by CLI, the README says Cursor, Claude Desktop, Kiro, Windsurf and VS Code all accept the same mcpServers wrapper. Cursor reads ~/.cursor/mcp.json, Claude Desktop reads claude_desktop_config.json, Kiro reads .kiro/settings/mcp.json, Windsurf reads ~/.codeium/windsurf/mcp_config.json, and VS Code reads .vscode/mcp.json:

{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here"
      }
    }
  }
}

After restarting the client, the Perplexity tools should appear in its tool list and a search-style prompt should route through them. Three optional variables are documented: PERPLEXITY_TIMEOUT_MS, defaulting to five minutes, PERPLEXITY_BASE_URL for a custom endpoint, and PERPLEXITY_LOG_LEVEL accepting DEBUG, INFO, WARN or ERROR, defaulting to ERROR. If you are behind a company proxy, the README says the server checks PERPLEXITY_PROXY first, then HTTPS_PROXY, then HTTP_PROXY, and connects directly if none are set:

export PERPLEXITY_PROXY=https://username:password@your-proxy-host:8080

There is also a self-hosted HTTP mode. The Dockerfile builds the TypeScript project in a node:22.12-alpine stage, copies dist into a node:22-alpine release image, exposes port 8080 and sets the entrypoint to node dist/http.js. The package scripts include start:http for that entry and a start:http:UNSAFE-public variant that sets BIND_ADDRESS=0.0.0.0 with ALLOWED_ORIGINS=*, which the name flags as unsafe for good reason.

Where the Local Server Gets in Your Way

The npx route means the client resolves and runs a package from the npm registry each time it starts. On a locked-down network that fails, and the proxy variables only help once the process is running. The hosted endpoint is the cleaner answer there, but it depends on your client supporting remote MCP at all, which the README treats as an open question rather than a given. The Docker path is not a drop-in either: the image listens on port 8080 and its entrypoint is dist/http.js, so it is an HTTP service you must place behind your own access control, not a stdio server you point a desktop client at. The start:http:UNSAFE-public script binds to 0.0.0.0 and allows every origin, which is a development convenience and not a deployment posture. The README does not document rate limiting, key rotation, or what happens to in-flight research when PERPLEXITY_TIMEOUT_MS expires. It also does not describe rollback or version pinning for the npm package, so if you need reproducible installs you are choosing a version yourself rather than following a documented policy.

How This Differs from Calling the Perplexity API Directly

The obvious alternative is skipping MCP and calling the Perplexity API from your own code. The difference is where the integration lives. With a direct API call you own the request shape, the retry logic, the prompt construction and the place where results enter your application. With this server, that work is done for you, but the tool surface is fixed by the server and your client decides when to call it. A second alternative is a different MCP server entirely, such as a filesystem or memory server. Those expose local state to the model; this one exposes a paid external search and research service. They are not substitutes. If your problem is that the model cannot see your repository, a filesystem server is the right tool and this one is not. If your problem is that the model cannot see the web, this is the tool, and the choice you are actually making is hosted endpoint versus local process.

Licence, Maintenance and the Cost of Upgrading

The package is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That covers the code in this repository. It does not cover the Perplexity API itself, which is a separate commercial service governed by your account terms, and it does not change the fact that every tool call consumes your API quota. On maintenance, the last push to the repository was on 2026-09-25, three days before this writing, and the repository is not archived. The package version in package.json is 1.3.0. The upgrade story is asymmetric. The hosted endpoint updates on Perplexity's side, so there is nothing for you to do. The local package is pinned by whatever your client resolves, and since the README does not document a version pinning policy, an npx-based install can pick up a new release without you changing anything. If that matters, pin the version in your client config yourself.

Editorial conclusion

Adopt the hosted endpoint first if your client supports remote MCP: it is the same tool set with nothing to update. Install the local package only when your client cannot reach a remote server, or when a corporate proxy forces you to route traffic yourself via PERPLEXITY_PROXY. Before rolling it out, check that your client accepts the mcpServers wrapper, that your API key is supplied through the client's own secret handling, and that you actually want an assistant issuing live web queries on your behalf.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. perplexityai/modelcontextprotocol on GitHub
4. Project website
5. README