Skip to main content

Server and Web Sharing

Local MCP Bridge

Use pinakea from local stdio MCP clients like Claude Desktop, Codex, Cursor, and VS Code

pinakea includes a bundled local MCP bridge so desktop clients can read from your current library without needing the repository, npm, or a manual Node setup.

The bridge is available during the same one-time 30-day trial as Free chat and deep summaries. After that trial ends, the bundled MCP bridge requires Pro on an active Mac. See Paid Features for the full trial and Pro-feature rules.

Supported clients include:

  • Claude Desktop
  • Claude Code
  • Codex
  • Cursor
  • VS Code + Copilot
  • other local stdio MCP clients
Important

ChatGPT is not supported here. It expects a remote HTTP/OAuth integration, while pinakea’s MCP bridge is a local stdio process launched on your Mac.

Set scope

The MCP bridge always uses pinakea’s currently selected Set. It cannot switch Sets remotely. If you want a different library, switch Sets inside pinakea first. See Sets (Libraries).

Where to find it

Open pinakea → Settings (Cmd+,) → Server.

That pane contains two parts:

  • Browser access — the HTTP server for phones, tablets, other browsers, and Raycast remote mode
  • Local MCP bridge — bundle status, the generated config, and Copy MCP Config

If the trial has ended and this Mac is not entitled for Pro, the MCP section stays visible but Copy MCP Config is disabled and pinakea shows an upgrade or device-activation message.

What the MCP bridge exposes

The bundled MCP server is intentionally small and read-only. It exposes four tools:

  • pinakea_list_sources
  • pinakea_list_recent_items
  • pinakea_search
  • pinakea_get_item

Search scopes match the app’s server API:

  • auto (default)
  • titles
  • summary
  • content
  • semantic

Semantic search is fully supported. scope controls how pinakea matches and ranks results, not how much context comes back. When scope is omitted or set to auto, pinakea routes short/exact lookups such as Audi, URLs, UUIDs, paths, structured filters, and quoted phrases to Summary search. Descriptive phrases and questions such as why is Audi losing ground in the US market or Warum Audi route to Semantic search.

pinakea_search results include full AI summaries when available, regardless of search scope, so an MCP client can triage likely matches before calling pinakea_get_item. Semantic results also include relevance_score; higher is stronger, and scores below 0.50 are treated as low by pinakea’s hint rules. summary_confidence is a reliability signal for the summary; use pinakea_get_item for important claims when confidence is lower or the summary is not enough.

The response can include hints when a query is broad, low-relevance, missing many summaries, or fell back from Semantic to Summary search. These hints are sparse corrective signals: narrow after BROAD_RESULT_SET, rephrase after LOW_RELEVANCE_TAIL, and treat SEMANTIC_FALLBACK results as keyword/summary-ranked.

pinakea_list_recent_items stays lean: it returns titles and metadata only. Use it for chronological browsing or recent-item checks. Search and recent-list responses do not include tags; item tags remain available only on pinakea_get_item. If you want to restrict a tool call to one source, call pinakea_list_sources first and then pass an active source_namespace.

Setup

  1. Open Settings → Server.
  2. Confirm the MCP section says the bundle is ready.
  3. Click Copy MCP Config.
  4. Paste the generated config into your MCP client.

pinakea generates a Claude Desktop-style JSON snippet, but the same command and args work for other local stdio clients such as Codex, Cursor, and VS Code.

Note

The generated config points at the bundled runtime inside the app:

  • Contents/Resources/mcp-server/node
  • Contents/Resources/mcp-server/server.js

You should not need to edit those paths manually unless you are debugging a custom build.

How it behaves

  • The MCP bridge talks to pinakea’s local loopback server, not directly to the database.
  • pinakea must be running for MCP requests to succeed.
  • All MCP requests use a shared request helper with discovery across the local server port range and a 30 second timeout.
  • The bundled MCP bridge identifies itself to pinakea’s loopback API so pinakea can enforce the post-intro Pro gate without affecting Raycast.
  • Search telemetry never records raw query text, titles, URLs, UUIDs, source names, summaries, or tags. pinakea records only low-cardinality metadata such as scope, result-count buckets, and whether a later pinakea_get_item followed a search result.
  • If the bridge is locked, pinakea returns a clear upgrade/device-activation message and the MCP client should surface that message instead of a generic “offline” error.
  • pinakea_get_item returns only items visible in the current Set. If a cached UUID belongs to another Set, pinakea returns 404 instead of leaking content.

Browser access vs MCP

These are related, but not the same:

  • Browser access is for opening pinakea in Safari, Chrome, mobile browsers, or Raycast remote mode.
  • Local MCP bridge is for AI tools that launch a local stdio server process on your Mac.

Both live under Settings → Server, and both follow the currently selected Set.

Troubleshooting

  • The MCP client says pinakea is offline: make sure pinakea is running.
  • The MCP client says your trial has ended or this Mac is inactive: the bundled MCP bridge is locked. Upgrade to Pro or activate this Mac in Settings → License.
  • The MCP section says the bundle is missing: reinstall or rebuild pinakea so the bundled node and server.js are present.
  • Search works but results look wrong: check which Set is selected in pinakea.
  • A previously opened item stops working after switching Sets: this is expected. The bridge is Set-scoped, so old UUIDs from another Set return 404.

Related / Next