MCP server & agent scenarios

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

OY.Surf ships an MCP server so AI agents (Claude Code, Claude Desktop, Cursor…) can work with your library through the Model Context Protocol — entirely on your Mac.

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.

claude mcp add --transport http oy-surf http://127.0.0.1:8765/mcp

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

Every write action pops a native confirmation in OY.Surf; nothing is hard-deleted (cleanup goes to the Trash); the server is local-only and token-guarded. Original files never leave the machine — agents get thumbnails only, on request.