MCP server & agent scenarios

Let AI agents search, curate and organize your library — locally, token-guarded.

OY.Surf ships a local MCP server so connected agents such as Claude Code, Claude Desktop and Cursor can query your library. The server runs on your Mac; a connected client may send tool results to its own cloud model.

Enable & connect

Turn the MCP server on in Settings → Integrations. It listens on a local port (8765 by default) and is protected by a bearer token shown in Settings.

Use the command shown in Settings so it includes your actual port and bearer token. If you use this example, replace YOUR_TOKEN with that token; do not share it.

claude mcp add --transport http oy-surf http://127.0.0.1:8765/mcp --header "Authorization: Bearer YOUR_TOKEN"

What agents can do

• Understand your work — oy_whats_in_work returns your live working set, active folders and library totals.
• Hybrid search — oy_search_assets fuses filename/OCR/notes matching with on-device visual semantics, plus a tone filter (dark / light / vivid / muted).
• Build moodboards — oy_create_moodboard turns a query like “dark UI references” into a laid-out Canvas board and opens it in the app.
• Clean duplicates — oy_cleanup_duplicates reports duplicate groups (dry run) and, with your approval, keeps the best copy and moves the rest to the macOS Trash.
• Plus metadata, palettes, OCR, previews, notes and collections tools.

Safety

Changes such as ratings, collection edits, moodboard creation and duplicate cleanup ask for native confirmation. Additive note creation is also available to a connected client without a separate confirmation. Cleanup moves duplicate files to the Trash. The local server is token-guarded, but read tools can return metadata, thumbnails, full note text and your built voiceprint. Review the connected client’s permissions and data policies before giving it access.