How to run an MCP server over your notes

What is MCP, in one paragraph?

The Model Context Protocol (MCP) is an open standard that lets AI applications connect to tools and data. A server exposes capabilities - “search these notes”, “read this document” - and a client (Claude Code, Cursor, or any other MCP-capable agent) discovers and calls them. Instead of pasting your notes into a chat window, you hand the agent a controlled, queryable window into them.

That window is the interesting part. The rest of this post is about how to open it without opening everything else.

How does OmniFolder’s MCP server work?

OmniFolder ships an MCP server built into the app - your knowledge base becomes something an agent can search, read and remember through, with three properties that matter more than the feature list:

• Off until you start it. The server is not a background service. It runs when you start it in the AI panel and stops when you stop it.
• Bound to 127.0.0.1. Only processes on your own machine can connect. Your notes are never reachable from the network, and there is no relay in anyone’s cloud.
• Sharing is per node, and the default is nothing. An agent sees only the notes you explicitly shared in the app. Config alone grants no access - a project file that asks for sharing still has to intersect with what your machine trusts, and that trust is a click in the app, not a line in a repo.

The served tools cover the things an agent actually needs: hybrid search over meaning and words, reading a note’s layers, graph neighbors (“what links here”), and an append-only work diary agents use to leave reasoning for the next session.

How do I connect a client like Claude Code?

The app generates the exact configuration for you - AI panel → Sharing and external agents (MCP) → Server. The snippet is a standard .mcp.json entry: the server’s local URL plus a bearer token the app mints. It looks like this shape:

{
  "mcpServers": {
    "omnifolder": {
      "type": "http",
      "url": "http://127.0.0.1:<port>/mcp",
      "headers": { "Authorization": "Bearer <token generated by the app>" }
    }
  }
}

Two practical rules. First, treat the token like a secret - gitignore the config if it lives in a repo. Second, share deliberately: start with the handful of notes the agent needs, and widen only when a real task wants more. An agent that can see everything is a prompt-injection surface as wide as your vault.

Why bother? What does an agent do with my notes?

The dry answer: retrieval. The honest answer: memory. An agent working in your codebase can ask “where is this concept written down”, “what did we decide about X and why”, “what links to this document” - and get answers grounded in your writing instead of its training data.

We run this on ourselves: the OmniFolder repository’s own project memory is served to our coding agents by OmniFolder itself, over exactly this MCP server. The docs vault answers orientation questions that would otherwise cost five file reads, and the diary records the why behind decisions long after the chat that made them is gone.

What should I check before trusting any MCP setup?

Vendor-neutral checklist, ours included:

1. Where does the server bind? Loopback (127.0.0.1) means local-only. Anything else needs a reason.
2. What is the default share? “Everything, minus exclusions” and “nothing, plus explicit shares” are very different postures.
3. Is access revocable in one place? You should be able to see what is shared and turn it off without editing config files.
4. Is there an audit trail the agent cannot rewrite? Append-only logs beat editable ones - an audit trail the audited party can rewrite is not an audit trail.