Nexus
Sign inStart building
Guides / Brain

Connecting Perplexity

Perplexity connects over the internet, so the brain has to be reachable over HTTPS.

Perplexity Computer can use your brain as a connector, so it can search and write your notes while it works. Unlike a coding agent on your laptop, Perplexity runs in the cloud and connects to the brain over the internet. That means the brain has to be reachable at a public HTTPS address.

This guide gives the brain a fixed public address with an ngrok tunnel, starts the brain's HTTP server so it accepts tunneled connections, creates a scoped OAuth client, adds the connector in Perplexity, checks that it works, and shows how to cut access off again.

Time
25 minutes
For
People who run their own brain and want Perplexity Computer to use it

Before you start

  • A working brain on the machine that will serve it, with the nexusbrain CLI installed. Run every nexusbrain command in this guide on that machine.
  • A Perplexity plan that includes connectors. The setup text printed by nexusbrain connect refers to Perplexity (Pro).
  • An ngrok account. The Hobby tier gives a fixed domain that survives restarts; the free tier works, but its address changes every time ngrok restarts.
  • You have read Securing a shared brain, because this setup puts your brain on the internet.

01How the pieces fit

Perplexity sends MCP requests to https://<your-domain>/mcp. ngrok receives them and forwards them to the brain's HTTP server on your machine, which listens on port 3131 unless you choose another port.

The brain server binds to 127.0.0.1 by default. The nexusbrain connect output for Perplexity says that default bind refuses tunneled connections, so you start the server with --bind 0.0.0.0 and tell it its public address with --public-url.

PieceWhere it runsAddress
Brain HTTP server (nexusbrain serve --http)Your machinehttp://localhost:3131
ngrok tunnelYour machinehttps://your-brain.ngrok.app
Perplexity connectorPerplexity's cloudCalls https://your-brain.ngrok.app/mcp

02Give the brain a public HTTPS address

These steps follow the Public Tunnel recipe that ships with the brain (recipes/ngrok-tunnel.md). Replace your-brain.ngrok.app with the domain you claim.

  1. Install ngrok if it is not installed.

    On a Mac, run brew install ngrok. On Linux, the recipe downloads the ngrok v3 stable build for your platform and unpacks it into /usr/local/bin.

    You should seengrok runs from your terminal.

  2. Copy your ngrok authtoken and add it to ngrok.

    Sign in to the ngrok dashboard and open the authtoken page at dashboard.ngrok.com/get-started/your-authtoken. Put the value in NGROK_AUTHTOKEN, then run the command.

    ngrok config add-authtoken $NGROK_AUTHTOKEN

    You should seeThe command finishes without an error. If ngrok rejects the token, copy it again.

  3. Claim a fixed domain.

    In the ngrok dashboard, open Domains, click "+ New Domain", choose a name such as your-brain.ngrok.app and click Create. Skip this on the free tier, and expect the address to change on every restart.

    You should seeThe domain is listed in your ngrok dashboard.

  4. Start the tunnel to the brain's port.

    The recipe's example forwards port 8765 for a voice agent. For the brain, forward the port nexusbrain serve --http listens on: 3131 by default, or the value you pass to --port. On the free tier, run ngrok http 3131 without --url.

    ngrok http 3131 --url your-brain.ngrok.app

    You should seengrok keeps running in the terminal and shows your public address forwarding to port 3131.

  5. Confirm the tunnel is active.

    curl -sf http://localhost:4040/api/tunnels

    You should seeJSON describing the tunnel, including its public_url.

Tip

The tunnel must be running whenever Perplexity needs the brain. The recipe includes a watchdog script, run from cron every 2 minutes, that restarts ngrok if it stops.

03Start the brain for tunneled connections

  1. Start the HTTP server bound to all interfaces, with your public address.

    --public-url becomes the OAuth issuer. It must be exactly the HTTPS address Perplexity uses, or OAuth clients reject the tokens.

    Leave --enable-dcr off. Perplexity uses a client you register yourself in the next section.

    nexusbrain serve --http --bind 0.0.0.0 --public-url https://your-brain.ngrok.app

    You should seeA startup box with Port 3131, Bind 0.0.0.0, Issuer https://your-brain.ngrok.app and "DCR: disabled". A warning that NEXUS_BRAIN_HTTP_CORS_ORIGIN is unset is expected; it only affects cross-origin browser requests.

  2. Check the brain through the tunnel.

    curl https://your-brain.ngrok.app/health

    You should seeA JSON reply with "status":"ok", the version and the engine.

Warning

Your brain is now reachable by anyone who knows the address. Every request still needs a valid token, but keep credentials private, keep DCR off, and stop the tunnel when you do not need it.

04Create credentials for Perplexity

Perplexity accepts either an OAuth client or a bearer token. OAuth is the recommended path for a cloud service: Perplexity holds a client ID and secret and gets short-lived, scoped access tokens, instead of holding one long-lived key with full access.

  1. Register an OAuth client and print the connector fields.

    This runs nexusbrain auth register-client for you with the client_credentials grant and the scopes read write. To give Perplexity read access only, add --scopes read.

    The client is named nexusbrain unless you pass --name perplexity (lowercase letters, digits, _ and -).

    nexusbrain connect https://your-brain.ngrok.app/mcp --agent perplexity --oauth --register

    You should seeA block that starts "# In Perplexity (Pro): Settings → Connectors → add a remote MCP server:" and lists URL, Auth "OAuth 2.1 (client credentials)", Issuer URL, Client ID and Client Secret.

  2. Save the client ID and secret somewhere safe.

    The secret is shown only this once. Store it like a password. You need the client ID later to revoke access.

    You should seeYou have the Client ID (starting nexusbrain_cl_) and the Client Secret saved.

  • Already have a client? Pass it instead of registering a new one: nexusbrain connect https://your-brain.ngrok.app/mcp --agent perplexity --oauth --client-id nexusbrain_cl_xxx --client-secret nexusbrain_cs_xxx.
  • Prefer a bearer token? Create one with nexusbrain auth create "perplexity", then run nexusbrain connect https://your-brain.ngrok.app/mcp --agent perplexity --token <token>. The printed block uses Auth "Bearer token (API key)". This token has full access and does not expire.
  • Add --json to get the same fields as JSON. Secrets are shown as *** unless you also pass --show-token.

05Add the connector in Perplexity

  1. In Perplexity, open Settings, then Connectors, and add a remote MCP server.

    You should seeA form for a new remote MCP connector.

  2. Enter the URL.

    Use the URL line from the printed block, https://your-brain.ngrok.app/mcp.

    You should seeThe URL field holds your /mcp address.

  3. Choose OAuth 2.1 client credentials and fill in the fields.

    Copy Issuer URL, Client ID and Client Secret exactly as printed. If you used a bearer token, choose the bearer token (API key) option and paste the token instead.

    You should seeAll fields from the printed block are filled in.

  4. Save the connector and ask Perplexity to use it.

    The printed block suggests the first calls: get_brain_identity to learn whose brain this is, then list_skills. If list_skills fails, skill publishing is off on the host; the core tools (search, query, get_page, put_page, think, find_experts) still work. To turn publishing on, run nexusbrain config set mcp.publish_skills true on the host.

    You should seePerplexity can answer a question using results from your brain.

06Verify and revoke access

  1. Watch requests arrive.

    Open http://localhost:4040 on the brain machine. The ngrok inspector shows every request through the tunnel with its headers, status and timing. The Request Log in the brain's admin dashboard at http://localhost:3131/admin shows the MCP calls themselves.

    You should seeRequests to /mcp appear in the inspector with a success status, and the calls show up in the Request Log.

  2. If you used a bearer token, run the built-in smoke test.

    nexusbrain auth test https://your-brain.ngrok.app/mcp --token <token>

    You should seeChecks for the initialize handshake, tools/list with a tool count, and get_stats, then "Your brain is live!" with the elapsed time.

  3. Revoke the OAuth client when Perplexity should lose access.

    This deletes the client and all its tokens. For a bearer token, run nexusbrain auth revoke "perplexity" instead. Remove the connector in Perplexity as well.

    nexusbrain auth revoke-client nexusbrain_cl_xxx

    You should seeOAuth client revoked, followed by "Tokens and authorization codes purged via cascade."

07Troubleshooting

Perplexity cannot connect, and the brain printed "[serve-http] WARNING: --public-url is set but --bind is not."

The server is listening on 127.0.0.1 only and refuses tunneled connections. Restart it with nexusbrain serve --http --bind 0.0.0.0 --public-url https://your-brain.ngrok.app.

OAuth fails even though /health works through the tunnel.

Check that --public-url is exactly the HTTPS address in the connector, with no path. The startup box shows it as the Issuer. If ngrok gave you a new address after a restart (free tier), restart the brain with the new --public-url and update the connector.

nexusbrain connect stops with "Could not register an OAuth client (run this on the brain host where the DB lives)".

Run the command on the machine that holds the brain's database. You can also register the client by hand with nexusbrain auth register-client perplexity --grant-types client_credentials --scopes "read write" and pass the result with --client-id and --client-secret.

nexusbrain connect says "Add an explicit scheme, e.g. https://..." or "Unexpected path".

Pass the full address including https:// and ending in /mcp, for example https://your-brain.ngrok.app/mcp. A bare host or another path is rejected.

nexusbrain connect stops with "--oauth needs BOTH --client-id and --client-secret (or use --register to mint a client)."

Pass both values of an existing client, or use --register to create a new one.

Adding --install fails with "--install supports claude-code and codex."

Perplexity is set up through its own settings screen. Drop --install and copy the printed fields into Perplexity.

Perplexity reports invalid_client or "Client has been revoked".

The client was revoked or the secret was copied wrong. Register a new client with nexusbrain connect https://your-brain.ngrok.app/mcp --agent perplexity --oauth --register and update the connector.

The connector stops working after the computer restarts.

ngrok and nexusbrain serve --http do not start on their own. Start both again, or set up the watchdog from the ngrok recipe so the tunnel restarts automatically.