Skip to main content

Usage

Server - Local MCP Bridge - ONA.UNO Docs

Use ONA.UNO from local stdio MCP clients like Claude Desktop, Codex, Cursor, and VS Code

ONA.UNO 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.

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 ONA.UNO’s MCP bridge is a local stdio process launched on your Mac.

Set scope

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

Where to find it

Open ONA.UNO → 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 ONA.UNO 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:

  • ona_list_sources
  • ona_list_recent_items
  • ona_search
  • ona_get_item

Search scopes match the app’s server API:

  • titles
  • summary
  • content
  • semantic

Semantic search is fully supported. That is the main reason to use the bridge from an MCP client.

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.

ONA.UNO 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 ONA.UNO’s local loopback server, not directly to the database.
  • ONA.UNO 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 ONA.UNO’s loopback API so ONA.UNO can enforce the post-intro Pro gate without affecting Raycast.
  • If the bridge is locked, ONA.UNO returns a clear upgrade/device-activation message and the MCP client should surface that message instead of a generic “offline” error.
  • ona_get_item returns only items visible in the current Set. If a cached UUID belongs to another Set, ONA.UNO returns 404 instead of leaking content.

Browser access vs MCP

These are related, but not the same:

  • Browser access is for opening ONA.UNO 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 ONA.UNO is offline: make sure ONA.UNO 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 ONA.UNO so the bundled node and server.js are present.
  • Search works but results look wrong: check which Set is selected in ONA.UNO.
  • 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