---
title: Pinako AI Bridge & MCP Setup
description: Connect Claude, ChatGPT, Cursor, VS Code, and other AI clients to Pinako over MCP.
canonical: https://pinako.pro/docs/mcp-setup/
---

# Pinako AI Bridge & MCP Setup

> Markdown version of https://pinako.pro/docs/mcp-setup/ - same content, agent-friendly format.
> Site map for agents: https://pinako.pro/llms.txt

_Detailed setup, per-client configuration, and troubleshooting for connecting your own AI app to your Pinako workspace over MCP_

For information regarding Pinako's AI features in general, refer to the [Pinako AI Librarian](#guide-ai-librarian) section of the user guide. It covers natural language search, the built-in AI chat panel, what an AI assistant can read and change in your workspace, monthly AI credits, and basic AI Bridge installation.

This page picks up where the user guide leaves off and covers the full setup for connecting your own AI app to Pinako over MCP: step-by-step instructions for both connection methods, manual configuration for clients the installer does not detect on its own, the complete list of what your AI can see and do once connected, and troubleshooting. It is aimed at people who want more detail than the quick start in the user guide provides.

There are two ways to make the connection. The **local bridge** is a small desktop download that runs on your own computer. The **remote connector** is hosted by Pinako, so there is nothing to install: you paste one URL into your AI app. Both give your AI the same read and write access to your workspace, and both run on your own AI subscription rather than your monthly Pinako AI credits.

## Which one should you use? {#bridge-vs-connector}

-   **Using desktop agents on Windows or Linux:** install the [local bridge](#local-bridge). It runs on your own machine, so responses are faster and your data never leaves your computer.
-   **Using desktop agents on ChromeOS or macOS, or with websites like ChatGPT.com, Claude.ai, or Grok.com:** use the [remote connector](#remote-connector). It needs no install and works where a local download cannot run.

|  |  |  |
| --- | --- | --- |
|  | Local bridge | Remote connector |
| --- | --- | --- |
| **Install** | Download and run an installer | None; paste a URL into your AI app |
| **Where it works** | Windows and Linux desktops | ChromeOS, macOS, web-based AI apps, and other connector-capable apps |
| **Speed** | Fastest; nothing leaves your machine | Slightly slower; routes through Pinako's server |
| **Your data path** | Stays on your computer, with no Pinako server in between | Relays through Pinako's server to your browser |
| **Works offline** | Yes, including with a local AI model | No; needs an internet connection |

## Local bridge (download) {#local-bridge}

The local bridge exposes your tab trees, libraries, notes, tags, memos, browser bookmarks, and chronology to external AI clients through the **Model Context Protocol (MCP)**. Once connected, your AI assistant can read and act on everything in your Pinako workspace using natural language: search and answer questions, as well as edit metadata, reorganize tabs and libraries, and write or restructure notes.

The bridge runs locally on your machine. Your data stays on your computer and is never sent to a third-party server. The AI client's own model handles all reasoning, and edits are dispatched back to the local extension through the same channel.

> **Requirement:** Pinako AI Bridge requires a **Pinako Pro** (or above) subscription. The connection activates automatically when you sign in to a Pro account in the extension.

> **Looking for an in-extension chat?** The MCP Bridge is especially useful when you already use Claude Desktop, Cursor, or another desktop AI client and want it to move information between Pinako and your other tools, files, and services. Ask it to copy a library's notes into a Google Doc, build a spreadsheet from the tabs in a research library, or visit the URLs from a library and prepare a report. If you'd rather chat with an AI that lives directly in the Pinako popup (billed against your monthly Pinako AI credits, or your own API keys), see the [AI Chat Panel](#guide-ai-chat) section of the user guide.

## How It Works {#bridge-how-it-works}

The bridge consists of two parts that run together:

1.  **Chrome Native Messaging host:** a local process that communicates with the Pinako extension via Chrome's native messaging protocol, receiving your live tab tree data.
2.  **MCP server:** an HTTP server on `localhost:37421` that serves your data to AI clients using the standard MCP protocol.

When an AI client asks about your tabs, the MCP server responds from its in-memory cache of your latest tree data. The extension pushes updates automatically whenever your tabs change.

## Quick Start {#bridge-quick-start}

1.  **Download and run the installer.**
    -   **Windows:** Run the graphical installer. It detects your AI apps and displays a checklist. Select some or all of them, and it configures them automatically.
    -   **Linux:** Download the CLI executable for your architecture (x64 or ARM64), make it executable (`chmod +x`), and run it from a terminal. It walks you through the same detection and configuration steps.
        
        ```
        chmod +x pinako-ai-bridge-cli-linux-x64
        ./pinako-ai-bridge-cli-linux-x64
        ```
        
2.  **Restart your AI apps.** Close and reopen any configured apps so they pick up the new MCP settings.
3.  **Activate the connection.** Click the Pinako icon in your browser toolbar to open the extension. This starts the bridge.
4.  **Ask your AI.** Try something like _"What tabs do I have open?"_ or _"Find my tabs about machine learning."_

> **Tip:** The installer creates an MCP configuration entry for each selected app. You can re-run it later to add more apps or update the configuration.

## Supported AI Clients {#supported-ai-clients}

The installer auto-detects and configures the following clients:

|  |  |  |
| --- | --- | --- |
| Client | Platform | Config type |
| --- | --- | --- |
| Claude Code | Win / Linux | JSON (HTTP) |
| Claude Desktop | Win / Linux | JSON (stdio) |
| ChatGPT-Codex (app / CLI / IDE) | Win / Mac / Linux | TOML (HTTP) |
| Cursor | Win / Linux | JSON (HTTP) |
| VS Code (Copilot agent mode) | Win / Linux | JSON (HTTP) |
| Antigravity | Win / Linux | JSON (HTTP) |
| Grok Build | Win / Linux | TOML (HTTP) |
| Kimi Code | Win / Linux | JSON (HTTP) |
| OpenClaw | Win / Linux | JSON (HTTP) |
| Hermes | Win / Linux | YAML (HTTP) |
| Cline (VS Code) | Win / Linux | JSON (HTTP) |
| Zoo Code (VS Code) | Win / Linux | JSON (HTTP) |
| Windsurf \* | Win / Linux | JSON (HTTP) |
| Roo Code (VS Code) \* | Win / Linux | JSON (HTTP) |
| Continue.dev \* | Win / Linux | YAML (HTTP) |
| Gemini CLI \* | Win / Linux | JSON (HTTP) |
| Any HTTP MCP client | Any | URL endpoint |

\* No longer developed by its vendor; existing installs are still detected and configured. Zoo Code is Roo Code's successor, and Antigravity succeeds Gemini CLI.

Most clients connect over **HTTP**; the installer writes the endpoint into each app's own MCP config file (Claude Desktop uses a small bundled **stdio** shim instead). Any other MCP-capable app can connect manually — point it at:

> HTTP endpoint  
> `http://127.0.0.1:37421/mcp?token=YOUR-TOKEN`

> **The address includes an access token.** The installer generates one and writes it into every app it configures, so apps set up automatically need nothing from you. To configure an app by hand, copy the full address from the installer's final screen, or read the token from `%APPDATA%\Pinako\mcp-auth-token` on Windows (`~/.local/share/pinako/mcp-auth-token` on Linux, `~/Library/Application Support/Pinako/mcp-auth-token` on macOS). Treat the address like a password: anyone who has it can read and change your tabs, libraries, and notes. An app connected without the token can still read your data but cannot change it.

> **Note:** The HTTP endpoint is only available while the Pinako extension is open and the bridge is running.

**ChatGPT Desktop**

ChatGPT Desktop isn't in the auto-configure list above. OpenAI's MCP connector system accepts only public HTTPS URLs and rejects loopback addresses like `127.0.0.1` with an _"Unsafe URL"_ error. Since the bridge runs at `http://localhost:37421/mcp` on your own machine, ChatGPT Desktop can't reach it directly.

If you already run a tunneling service that gives the bridge a public HTTPS URL (Cloudflare Tunnel, ngrok, Tailscale Funnel, or similar), you can connect ChatGPT manually:

1.  Start your tunnel pointing at `127.0.0.1:37421`. You will get a public HTTPS URL such as `https://your-tunnel.example/mcp`.
2.  **Tell the tunnel to rewrite the Host header**, or the bridge will refuse the request. The bridge only answers requests addressed to itself as `127.0.0.1` or `localhost`, which is what stops a web page from reaching it. Tunnels forward their own public hostname by default, so pass `--host-header=rewrite` with ngrok, or `--http-host-header 127.0.0.1:37421` with cloudflared. If your tunnel cannot rewrite it, list the public hostname in the `PINAKO_ALLOWED_HOSTS` environment variable instead (comma-separated).
3.  Append your access token to the URL, exactly as the installer's final screen shows it — for example `https://your-tunnel.example/mcp?token=YOUR-TOKEN`. Without it ChatGPT can read your data but cannot change it.
4.  Open ChatGPT Desktop and turn on Developer Mode under **Settings → Apps & Connectors → Advanced**. This requires a ChatGPT Pro, Team, Enterprise, or Edu plan.
5.  Go to **Settings → Connectors → Create**. Paste your tunnel URL and save.
6.  Open the Pinako extension popup so the bridge starts running.
7.  Ask ChatGPT a question that uses Pinako (for example, _"List my Pinako libraries"_).

> **Important:** The tunnel URL acts as a credential for your tab data, so keep it private. We do not bundle a tunneling service or auto-configure ChatGPT for this reason. If OpenAI begins accepting loopback connections in the future, we will add ChatGPT to the auto-configure list.

## Remote connector (no install) {#remote-connector}

The remote connector is hosted by Pinako. You add one URL to your AI app, sign in to approve the connection, and your AI can read and act on your Pinako workspace, including from a Chromebook or a web-based AI app. There is nothing to download.

> Connector URL  
> `https://connect.pinako.pro/mcp`

Works with online AIs like ChatGPT, Claude, or Grok, and desktop apps like Claude Desktop. Any AI app that supports custom connectors can connect by pasting the URL above. Some apps require a paid plan to add your own connector.

**To connect:**

1.  In your AI app, add a custom connector (sometimes called a _remote MCP server_ or _app_).
2.  Paste the connector URL above. Leave any token or header fields blank.
3.  Your AI app sends you to pinako.pro to sign in and approve the connection. If your AI still does not see Pinako afterwards, fully quit the app and reopen it. Starting a new chat is not always enough.
4.  Click the Pinako icon to open it in a browser signed in to your account, then ask your AI something like _"List my Pinako libraries."_ Your AI reaches your workspace through that browser, so leave it open.

> **Requirement:** The remote connector requires a **Pinako Pro** (or above) subscription, and the Pinako extension open in a browser somewhere on your account so your AI can reach your live workspace.

## What your AI can see {#what-your-ai-can-see}

Your AI client has access to your Pinako workspace through these capabilities:

-   **See your full tab tree** (`get_tree`). Every window, group, and tab, including titles, URLs, favicons, your memos, your tags, opened-dates, and which tabs are ghost (closed) versus live.
-   **Search your tabs by keyword or tag** (`search_tabs`). Matches against titles, URLs, memo text, and tags. Prompts like _"find my tabs tagged science"_ or _"which tabs mention machine learning"_ work directly.
-   **Search across every scope at once** (`search_pinako`). Literal full-text search over your main tree, libraries, browser bookmarks, and notes in a single call, with an optional _exact-tag_ filter for tag-only matches.
-   **List your saved libraries** (`list_libraries`). Names, descriptions, and tab counts.
-   **Read inside a specific library** (`get_library`). Folders, tabs, your memos, your tags, and any notes attached to that library.
-   **Read your Main Notes** (`get_main_tree_notes`). The top-level notebook documents that aren't attached to any library.
-   **See which browsers you're running** (`list_browsers`). When Pinako is open in more than one browser, the AI can target a specific one (_"my Brave tabs"_, _"list libraries from Chrome"_).
-   **Read your browser bookmarks** (`get_bookmarks`). Folder hierarchy, titles, and URLs from your browser's native bookmark tree, so the AI can suggest reorganizations or pull bookmarks into a library.
-   **Find duplicates across scopes** (`find_duplicates`). Scans your tree, libraries, bookmarks, or any combination for URLs that appear in more than one place, so the AI can suggest cleanups.

The bridge exposes only your tab-tree, library, notes, and bookmark data. Subscription, billing, and account history aren't accessible.

## What your AI can do {#what-your-ai-can-do}

Beyond reading and answering questions, your AI can act on your Pinako workspace through a full set of write tools, using requests such as: _"organize my AI research tabs into a new library"_, _"tag every Tailwind tab with #design"_, _"clean up the duplicate bookmarks in my Design Library"_, or _"create a Note document summarizing the tabs in my Market Research Library by topic"_

-   **Tag, color, rename, annotate.** The AI can set or add tags, edit memos, change a node's star color, change row color of folders and groups, and rename tabs or windows.
-   **Reorganize the tree.** Move tabs and windows around, indent to nest, or outdent, create groups, ghost tabs (close in browser, keep in tree), or remove ghost-only branches.
-   **Manage browser Tab Groups.** Create a Tab Group from tabs you name, rename it, change its color, collapse or expand it, or ungroup it while leaving the tabs open. Works on live browser groups and on closed groups kept in your tree.
-   **Manage libraries and library groups.** Create new libraries, rename or describe them, add tabs from your tree or another library or your bookmarks, delete an entire library, create or rename library groups, reorder cards in the panel, dissolve groups, or delete library groups along with their libraries.
-   **Reorganize your browser bookmarks.** Move bookmarks and bookmark folders, rename them, delete them, create new folders, or push tabs from elsewhere in Pinako into a bookmark location. Bookmark writes round-trip into your browser's native bookmark manager.
-   **Write and edit notes.** Create new Main Notes or library notes, append to or replace existing notes, or delete a note entirely, with tier-based content limits (50K Pro / 150K Pro+ / 250K Premium / 500K Enterprise per note).
-   **Run multi-step plans atomically.** A single `bulk_apply` can chain up to 250 operations into one undo entry, so a complex reorganization either fully succeeds or leaves your tree unchanged.

Every write your AI performs is logged to your private Pinako audit table, scoped to your account. You can review what an agent did to your data after the fact.

## Approving destructive actions {#approving-destructive-actions}

Some operations close live tabs or remove persistent content. Every agent edit is undoable from Pinako's in-session undo stack, but once the popup closes the destruction is final, so Pinako requires the AI to obtain your explicit approval before these can run. The flag is set by your AI client after it asks you in chat; Pinako enforces that the flag is present, and rejects ops without it.

If you'd rather pre-approve destructive ops for a session rather than confirm each one, see [Granting standing approval](#granting-standing-approval) below for the bypass toggle in each AI client.

Operations that require confirmation:

-   **Closing live tabs and removing the saved nodes too** (`delete_live_node`). The browser tabs close and the tree record is removed in one step.
-   **Deleting a saved node from the tree** (`delete_node`). The node's tags, memo, custom title, and any nested children are lost permanently. Only ghost (closed) nodes are eligible; live tabs are refused here and need `delete_live_node` instead.
-   **Deleting an entire library** (`delete_library`). The library's tabs, metadata, and notes are removed.
-   **Deleting a library group AND all its libraries** (`delete_library_group` with cascade). One-way at the library-content level: the group structure can be recovered via undo, but the cascaded libraries' contents cannot.
-   **Deleting a note** (`delete_note`). The note's content is removed; the library or main tree it was attached to is unaffected.

Closing live tabs while keeping the saved tree node (`ghost_node`) and plain dissolve of a library group (libraries kept) do _not_ require confirmation. Both are fully undoable from Pinako's undo stack.

### Granting standing approval {#granting-standing-approval}

By default, AI clients prompt you for approval per tool call. If you trust the AI for a session and want it to stop asking, every major client supports a "trust" or "auto-approve" mode:

-   **Claude Desktop:** Settings → Developer → toggle _Auto-approve tools_, or per-server allowlist.
-   **Cursor:** Agent settings → _Auto-run_ or _Yolo mode_, optionally per-tool.
-   **Cline:** auto-approve toggle in the panel header, with a tool-specific allowlist.
-   **Roo Code:** approval mode dropdown (_manual_ / _auto_ / _auto-approve-safe_).
-   **Continue.dev:** per-tool allowlist in `config.json`.

Pinako has snapshot history, undo, and a permanent audit log per account, so granting standing approval is reasonable for everyday use. If something goes sideways, the safety nets recover it.

> **Recovery:** Every AI write is undoable from the toolbar undo button (Pinako stacks them like manual edits). The audit log at your Pinako workspace level records every successful and failed AI write with a per-row timestamp, so you can always answer "what did the AI do to my data, and when?".

## Troubleshooting {#mcp-troubleshooting}

### AI client can't connect

1.  Make sure the Pinako extension is open (click the toolbar icon).
2.  Check that the bridge process is running:
    -   **Windows:** Look for `pinako-mcp-service.exe` in Task Manager.
    -   **Linux:** Run `pgrep -f pinako-mcp-service`.
3.  Verify the MCP config entry exists in your AI client's settings.
4.  Restart the AI client after configuration changes.

### Bridge stops when extension closes

The bridge runs as a Chrome native messaging host; it starts when the extension opens and stops when it closes. Keep the Pinako popup open while using AI tools.

### Port conflict

If port `37421` is already in use, the bridge will fail to start. Check for other processes using that port and stop them.

## Uninstalling {#uninstalling-the-bridge}

### Windows

Run **Add or Remove Programs** and uninstall _Pinako AI Bridge_. This removes the native host, the MCP server, and the native messaging manifest. You may also want to remove the `"pinako"` entry from each AI app's MCP config file.

### Linux

1.  Delete the `~/.local/share/pinako/` folder (contains the MCP service and native host manifest).
2.  Remove the `"pinako"` entry from the MCP config file of each AI app you configured.
3.  _(Optional)_ Delete the native messaging host symlinks:  
    `~/.config/google-chrome/NativeMessagingHosts/com.pinako.mcp.json`  
    `~/.config/chromium/NativeMessagingHosts/com.pinako.mcp.json`