Skip to main content

Claude Desktop Integration

There are two ways to connect Claude Desktop to PortDive:

  1. Remote Connector (recommended) — no install, OAuth login, automatic token refresh.
  2. Local install (stdio) — binary on your Mac, personal access token.

For most users the Remote Connector is the simplest path.

Prerequisites​

  • Claude Desktop with a Pro or Max plan (the Connectors feature is part of those plans)
  • A PortDive account

1. Open Connectors settings​

In Claude Desktop, open Settings → Connectors. You see your active connectors and an Add custom connector button at the bottom:

Connectors overview

2. Add a custom connector​

Click Add custom connector and fill in:

  • Name: portdive
  • URL: https://mcp.portdive.app/mcp

Add custom connector dialog

Confirm with Add. Claude registers itself via Dynamic Client Registration and creates the entry in your Connectors list.

3. Connect the connector​

The portdive connector appears with the CUSTOM badge and the configured URL in your Connectors list. Click Connect to start the OAuth handshake.

Connector ready to connect

4. Sign in to PortDive​

Your default browser opens on the PortDive sign-in page. Pick your preferred login (Google, Apple, or GitHub):

PortDive auth bridge

5. Allow the browser to return to Claude Desktop​

After signing in, the browser asks whether it can open Claude Desktop. Confirm with Allow:

Browser confirmation

6. Connector active​

After confirmation, the Connect button switches to Configure. The connector is now active and Claude Desktop can call the PortDive tools:

Connector connected

Why a globe icon instead of the PortDive logo?

At present, Claude Desktop renders custom connectors with a generic globe icon — regardless of any logo the server advertises. Real connector icons are reserved for entries in Anthropic's official catalog. Once PortDive ships there, the octopus will appear in this slot.

7. Test the connection​

Enter the following prompt in Claude:

Use the PortDive MCP server and run a health check for the thesis
"US Market Health Dashboard — SPX · SPY · QQQ · IWM" (ID 9).
Show signals, performance, and data freshness.

Claude now talks directly to your PortDive data.

Why Remote Connector?

No install, no token management, automatic background refresh, OAuth 2.1 + PKCE — this is the simplest and most modern path.

Alternative: local install (stdio)​

Use this variant only if you prefer a local binary or need a long-lived personal access token (PAT) instead of an OAuth session — e.g. for scripting or air-gapped environments.

Quick start

The setup wizard in the PortDive settings automatically creates a token and displays the ready-to-copy configuration.

macOS​

1. Open Developer settings​

Open Claude Desktop and navigate to Settings. You can access settings via the menu or ⌘ + ,.

Claude Desktop Settings

Select Developer under Desktop app in the left menu:

Developer settings

2. Edit configuration file​

Click the Edit Config button. This opens the folder containing the configuration file:

Configuration folder

Open the file claude_desktop_config.json with a text editor (e.g., TextEdit, VS Code, or your preferred editor).

File path

The configuration file is located at:

~/Library/Application Support/Claude/claude_desktop_config.json

3. Add MCP server configuration​

You'll see a JSON file with an empty "mcpServers": {} entry:

Empty configuration

Replace the empty "mcpServers": {} block with the following configuration. You'll get the token from the setup wizard — it's automatically created and ready to copy:

"mcpServers": {
  "portdive": {
    "command": "/usr/local/bin/portdive-mcp",
    "env": {
      "PORTDIVE_ACCESS_TOKEN": "pdv_YOUR_TOKEN_HERE"
    }
  }
},

Replace pdv_YOUR_TOKEN_HERE with your personal access token. The result should look like this:

Configuration inserted

Don't forget the comma

Make sure there is a comma after the closing brace of "mcpServers" if other entries like "preferences" follow. The setup wizard already includes the trailing comma.

4. Save and restart​

  1. Save the file (⌘ + S)
  2. Quit Claude Desktop completely (⌘ + Q)
  3. Restart Claude Desktop

5. Test the connection​

Enter the following prompt in Claude to test the connection:

Use the PortDive MCP server and run a health check for the thesis
"US Market Health Dashboard — SPX · SPY · QQQ · IWM" (ID 9).
Show signals, performance, and data freshness.

Test prompt in Claude Desktop

If the connection is successful, Claude will display signals, performance, and data freshness for the thesis.

Windows​

Coming soon

The local Windows installer is being prepared alongside the Windows binary. In the meantime use the Remote Connector — it works on every platform.

Next step: Learn more about using the MCP server in your daily workflow.