Skip to main content

Web Server and Remote Access

MCP Connector

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

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

MCP Connector is available on Free, Pro Monthly, and Pro Lifetime. See Paid Features for how the Free monthly processing limit works.

MCP Connector reads your real library, so pinakea must be signed in and this Mac must be active on the account.

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 MCP Connector uses a local stdio process launched on your Mac.

Set scope

MCP Connector 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+,) → Web Server.

That pane contains two parts:

  • Web Server — the HTTP server for phones, tablets, other browsers, and Raycast remote mode
  • MCP Connector — bundle status, the generated config, and Copy MCP Config

The MCP section stays visible when the bundle is present, and Copy MCP Config remains available even if this Mac is temporarily locked for account/device access. Actual MCP library requests still require pinakea to be signed in and this Mac to be active. If setup fails, pinakea shows a bundle, local server, or configuration message.

What MCP Connector 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

The semantic search tool 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 → Web 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

  • MCP Connector 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 runtime identifies itself to pinakea’s loopback API so pinakea can enforce the MCP route matrix. Raycast uses its own local-client marker and its own route matrix.
  • pinakea also checks that the account session is valid and this Mac is active before returning library data.
  • 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 a request is denied by route classification or setup state, pinakea returns a clear 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.

Web Server vs MCP

These are related, but not the same:

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

Both live under Settings → Web 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 a route is denied: make sure the copied MCP config points at the bundled runtime and that pinakea is running.
  • The MCP client says Sign in, Refresh Status, or Activate this Mac: open pinakea on this Mac and follow that action. Choose Activate this Mac only when this Mac is inactive; if the account already has five active Macs, deactivate one first.
  • 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