# Quick Start: Perplexity MCP

Canonical page: https://www.kuudo.com/docs/quick-start/perplexity/

Ask in Perplexity's own interface and have it answered from your live Amazon Ads, Seller Central, and Vendor Central data — campaign performance, inventory health, listing status — rather than from the public web.

Use Perplexity when you want to ask a question in Perplexity's own interface and have it answer from your Amazon data rather than the public web.

Perplexity offers two connector types, and they are at different stages. Its own documentation states that local connectors are available now on macOS, and that remote connectors are rolling out to paid subscribers first. Check the [local and remote overview](https://www.perplexity.ai/help-center/en/articles/11502712-local-and-remote-mcps-for-perplexity) for current availability before you plan a rollout.

| Path | Status | Use it when |
| --- | --- | --- |
| Local connector on macOS | Available now | You want a working connection today, on a Mac |
| Custom remote connector | Rolling out | Your organization needs a shared connector with no per-machine setup |

Both reach the same private endpoint. The local path runs a small bridge on your machine; the remote path has Perplexity call your endpoint directly.

Your MCP server hostname is private to your deployment. It comes from your cloud provider, belongs to your environment, and is not shared across customers. Replace `{your-private-mcp-host}` with the private host shown in your dashboard.

## Before you start

- Use a paid Perplexity plan. The free tier cannot add connectors.
- Create an API key from the dashboard **Keys** tab.
- Keep the key in `MCP_API_KEY` or another local secret source.
- Confirm the private MCP endpoint ends with `/mcp`.

```text
https://{your-private-mcp-host}/mcp
```

## Local connector on macOS

Perplexity's local connectors run a command on your machine. Your MCP server is remote, so the command runs `mcp-remote`, a standard bridge that speaks stdio to Perplexity and HTTPS to your endpoint.

You need the Mac App Store build of Perplexity, and Node.js so that `npx` is available:

```bash
brew install node
```

### 1. Install the helper

Open **Account settings → Connectors**. Perplexity prompts you to install **PerplexityXPC**, the helper that lets it talk to local servers. Install it before adding a connector.

### 2. Add the connector

Back in **Connectors**, click **Add Connector** and use the **Simple** tab:

| Field | Value |
| --- | --- |
| **Server Name** | Something clear, such as `Kuudo` |
| **Command** | The bridge command below |

```bash
npx -y mcp-remote https://{your-private-mcp-host}/mcp --header "Authorization: Bearer ${MCP_API_KEY}"
```

Click **Save** and wait for the connector to report **Running** in the list. A connector that never reaches Running has not started, and no amount of asking will reach it.

### 3. Enable and test

On the Perplexity homepage, toggle the connector on under **Sources**, then ask something only your account can answer:

```text
List my Amazon advertising campaigns and show the three with the highest spend last week.
```

The first tool call prompts you for confirmation.

## Custom remote connector

Use this once remote connectors are available on your plan. Perplexity calls your endpoint directly, so there is nothing to install per machine.

Open the settings page for the scope you want:

| Scope | Where |
| --- | --- |
| Your account only | **Account settings → Connectors** |
| The whole organization (admins) | **Enterprise settings → Permissions → Connectors permissions** |

For an organization connector, an admin must first turn on **Allow members to add custom connectors**. It is off by default.

Click **+ Custom connector** in the top-right, choose **Remote**, and fill in the form:

| Field | Value |
| --- | --- |
| **Name** | Something clear, such as `Kuudo` |
| **MCP Server URL** | `https://{your-private-mcp-host}/mcp` — HTTPS is required |
| **Description** | Optional. What the connector reaches, for others in the organization |
| **Authentication** | See below |
| **Transport** | **Streamable HTTP** |
| **Icon** | Optional, 128 KB maximum |

Check the acknowledgement box and click **Add**, then click the connector card to run the authentication flow and enable it. The ellipsis (**⋮**) on the card edits or removes it later.

Perplexity runs a verification probe when you save. If the connector saves without an error tag, the endpoint answered and the auth path worked end to end.

### Authentication

The remote form offers three application-layer methods and no free-form header field, so pick the one your deployment is configured for.

| Method | When to use it |
| --- | --- |
| **API Key** | A static key supplied at setup. Use the key from your dashboard **Keys** tab. |
| **OAuth 2.0** | Deployments configured for OAuth. Perplexity discovers endpoints and scopes automatically when the server publishes `/.well-known/oauth-authorization-server`; otherwise supply a Client ID and Client Secret. |
| **None** | Only when the endpoint carries its own credential, such as a pre-signed URL. |

If you register an OAuth application, the redirect URL is fixed:

```text
https://www.perplexity.ai/rest/connections/oauth_callback
```

Organizations on the Enterprise subdomain register this instead:

```text
https://enterprise.perplexity.ai/rest/connections/oauth_callback
```

For an organization-scoped OAuth connector, an admin can authenticate once for everyone, or require each member to authenticate individually.

### If your endpoint sits behind Cloudflare Access

Because your deployment runs in your own cloud, the MCP hostname is often fronted by a zero-trust edge. Perplexity authenticates to that edge before any application-layer auth runs, so the two stack rather than compete.

On the **+ Custom connector** form, set **Network access** to **Cloudflare Access** and supply both values. The key names are exact:

```text
CF-Access-Client-Id
CF-Access-Client-Secret
```

Perplexity injects these on every request, including the verification probe, so a bad token fails when you save rather than silently later. Values are stored encrypted and redacted in the interface.

On the Cloudflare side, do this once in the Zero Trust dashboard:

1. **Create a service token.** Go to **Access → Service Auth → Service Tokens**. Copy the Client ID and Client Secret immediately — the secret is shown only once.
2. **Create an Access application** of type **Self-hosted**, pointed at the public hostname Perplexity will call.
3. **Add a policy with Action set to `Service Auth`.** Include the service token from step 1.

Setting the action to **Allow** instead of **Service Auth** is the usual mistake. Allow expects an interactive browser login, which a machine client cannot satisfy, so the verification probe fails.

## Troubleshooting

### The local connector never reaches Running

Confirm Node.js is installed and `npx` resolves in the shell Perplexity inherits. Confirm `MCP_API_KEY` is set for that same environment — a variable exported in one terminal is not visible to an application launched from the Dock.

### Verification or tool calls return 403

Work through these in order:

- **Incomplete or expired service token.** Re-paste both values in full; the secret is long and partial pastes are easy to miss. Service tokens expire, one year by default.
- **Wrong policy action.** The Access policy must use **Service Auth**, not **Allow** or **Bypass**.
- **Propagation delay.** New Access applications, policies, and tokens take a few minutes to reach Cloudflare's edge. Wait, then retry before assuming a misconfiguration.
- **A challenge is blocking the request.** Perplexity connects from datacenter address ranges. If your zone challenges automated traffic, the endpoint receives a managed challenge no machine client can solve, which surfaces as a 403. Add a firewall skip or bot-management exception for the MCP hostname. Access still gates the endpoint through the service token.

If all four check out and it still fails, the problem is in the application layer rather than the edge.

### The connector saved but answers from the web

It is not enabled for that thread. Toggle it on under **Sources** before asking.

### Other members cannot see an organization connector

Sharing is a separate step. The creator has to share it from the **Permissions** screen in **Enterprise settings**, and newly shared connectors do not always appear immediately.

### The endpoint does not connect

Confirm the URL uses your private host, ends with `/mcp`, and is HTTPS. Perplexity rejects plain HTTP.

## Related docs

- [MCP Client Configuration](/docs/mcp-client-configuration/)
- [ChatGPT MCP](/docs/quick-start/chatgpt/)
- [NanoClaw MCP](/docs/quick-start/nanoclaw/)