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.

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

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.
  • 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 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