Skip to main content

What is MCP? A plain-English guide (and how it works in Koru)

Steven Liechti

Steven Liechtifounder of Koru

13 minute read
Diagram of an AI app using Koru's local MCP server to write a meeting-prep document and tasks.

Short answer

MCP is the Model Context Protocol, an open standard that lets an AI application use other programs' data and tools in a regular, agreed way. Koru ships an MCP server with the app, so the AI you choose can search your notes, create a document, and turn follow-ups into tasks, on your computer.

What is MCP?

MCP is the Model Context Protocol. It is an open standard for connecting an AI application to other programs, so the model can use those programs' data and tools in a regular, agreed way.

Without a shared protocol, every AI app needs a custom integration for every notes app, issue tracker or database it wants to touch. With MCP, the AI app speaks one protocol, and each product can ship a small server that describes what it can do. The same Claude, Cursor, Codex or Gemini session can then work with more than one of those products.

Koru ships one of those servers with the app. Once you connect it, the AI you choose can search your notes, write a new document, and turn follow-ups into tasks, on your computer.

MCP is maintained as an open specification. The protocol documentation lives at modelcontextprotocol.io. Koru did not invent MCP; it implements it.

Hosts, clients and servers

MCP has three roles, and the names are easier than they look.

The host is the AI application you are already using: Claude Desktop, Claude Code, Cursor, the ChatGPT desktop app, Gemini CLI, and other MCP-compatible tools. The host is in charge of the conversation, of starting connections, and of asking you before a tool is allowed to change something.

The client is a connector inside that host. You do not install a separate "MCP client" app. When the host connects to a server, it creates one client for that server. If you connect two servers, the host creates two clients. Each client talks only to its own server.

The server is the program that actually exposes capabilities. A server can run on your computer, or it can run remotely as a service. In Koru's case, the local server is a small executable named koru-mcp, installed next to the Koru app.

So the usual picture is: you chat with the host, the host uses a client to call the server, and the server asks Koru to read or edit your workspace.

Tools, resources and prompts

A server can offer three kinds of capability.

Tools are functions the model can call. "List my workspaces," "create a document," and "list open tasks" are tools. The model chooses when to call them, and a careful host will ask you to approve a change before it is made.

Resources are data the host can read and hand to the model as context, such as a documentation file the server publishes. Koru's server publishes a documentation resource at koru://docs/model, so a client can read the editing contract before it makes a change. If a client cannot read resources, the same text is available through a get_documentation tool.

Prompts are ready-made templates the user can invoke. Koru's MCP server does not publish prompts. Its useful surface is tools, plus that documentation resource.

Local servers and remote servers

MCP is the same protocol in both places. What changes is how the messages travel.

A local server uses standard input and output, usually called stdio. The host starts the server as a child process and speaks to it over those streams. When you disconnect, the host stops the process. This is how Koru's built-in server works: your client runs koru-mcp serve --stdio.

A remote server is typically reached over Streamable HTTP. The server listens at a URL, and the client posts MCP messages to it. That is the usual way to connect to a service that is not a process on your machine.

The official MCP specification describes these two standard transports. Older HTTP setups used a different streaming mechanism; new remote servers are expected to use Streamable HTTP.

How MCP works in Koru

Koru is a free, open-source notes app that works offline, on Windows, macOS and Linux. It works with the AI you choose. You write in rich text on your own computer, and you can sync between your devices peer to peer, end to end encrypted.

The MCP server ships in the same install as the app. On Windows it is koru-mcp.exe, on macOS it lives inside the app bundle at /Applications/Koru.app/Contents/MacOS/koru-mcp, and on Linux it sits next to koru in the folder you extracted. There is no plugin to enable inside Koru, and the local server does not need an API key.

When a client starts koru-mcp, the bridge does not rummage through your files on its own. Each tool call is forwarded to Koru on the same computer. Koru reads or writes your local database through the same document model the app uses, and it only reports success after the change is saved. What you get in Koru is an ordinary document or an ordinary task list, not a special "AI file."

You can copy the exact command from Koru's Welcome page, in the row labeled "Manage documents over MCP." That row is in Koru for Windows from 0.1.3 and for Mac from 0.1.4. On a Mac, move Koru.app to Applications first, rather than running it from the disk image, and open Koru once before you connect a client.

The Koru window does not have to stay open. The bridge looks for Koru's background service and can start it when the client needs it.

  • The local bridge talks only to Koru on your computer. Koru's service listens on 127.0.0.1, not on the public internet.
  • Nothing leaves your machine through the Koru server. If notes go to a model provider, that is because the MCP client you connected sent tool results along as part of the conversation, under that product's own terms.
  • The built-in local connection acts as you on that computer. It can read and edit every workspace Koru has there. Today there is no per-workspace picker and no read-only mode for this local connection, so only connect clients you trust.
  • Edits made through MCP are saved like your own. If you sync between devices, they travel the same way, including on peer-to-peer sync, which is end-to-end encrypted.

The server is open source, under the Mozilla Public License 2.0, in the Koru repository. The full setup, tool reference and troubleshooting notes are on Koru's MCP page.

With Koru Cloud, a Cloud API and Cloud MCP are also available. This guide focuses on the local server that ships with the app. For the cloud options, start at Koru for developers.

Example: create a meeting-prep document

This is the basic "give your AI your notes" loop, used to write something new.

Suppose you have a project workspace in Koru, and a meeting tomorrow. In Claude Code, Claude Desktop, Cursor, or another connected client, you can say something like:

"Look through my Koru workspace for anything about the Northwind review. Create a meeting-prep document titled 'Northwind review - prep' with a short agenda, a 'What we already know' section that summarizes the related notes, and an empty 'Decisions' section. Then open it in Koru."

Behind the scenes, the client uses Koru's MCP tools. It lists or searches your workspaces and documents, reads the notes that match, and calls create_document with that title and a complete body. Koru saves an ordinary document in the workspace. show_document can then open it in a Koru view you can keep editing yourself.

You can do the same for a project brief, a weekly recap, or a handoff doc. The point is not a new file format. The point is that the document is already in Koru, in your workspace, when the conversation ends.

Example: turn notes into tasks

Koru does not have a separate create_task MCP tool, and it does not need one. A task is a block in a document: the same kind of block you would create in the app. The server creates those blocks through the document tools, and it can also set a due date or a priority on them.

Say you already have a document of meeting notes, with follow-ups buried in the prose. You can ask:

"Read my 'Northwind review' notes in Koru. Turn each follow-up into a task, keep them in that document, and add a due date when the notes mention one. Then list my open tasks so I can check the result."

The client reads the document, then edits it to insert task blocks, or creates a new document to hold them if you asked for that instead. A due date is stored as a typed attribute on the task, not as a date typed into a sentence that the next tool has to guess at. After the edit, list_tasks can show what is now outstanding, across one workspace or all of them.

You can also ask the same client, later, to mark a task done or change a due date. Those are ordinary Koru task changes, made through the server and saved in the document.

If you want to see the work in the app, ask it to open the document in Koru. The tasks it created are the same tasks you would tick off by hand.

Connect an MCP client to Koru

Any MCP client that can launch a local stdio server can use the same command you copy from Koru's Welcome page: the full path to koru-mcp, then serve --stdio. The recipes below were checked against official client documentation, and against Koru's MCP page, on November 16, 2026. If a path in the examples does not match your install, use the command Koru copied for you.

Claude Code. In a terminal, not inside a Claude session, run claude mcp add koru -- and paste the command after it. On macOS:

bash
claude mcp add koru -- /Applications/Koru.app/Contents/MacOS/koru-mcp serve --stdio

On Windows, the path is the one Koru copied, for example:

bash
claude mcp add koru -- "C:\path\to\Koru\koru-mcp.exe" serve --stdio

On Linux, use the full path in the folder you extracted, for example:

bash
claude mcp add koru -- /home/you/koru/koru-mcp serve --stdio

The -- keeps Claude Code's own flags separate from the command that starts the server. By default the server is stored for the current project. Add --scope user before koru if you want it in every project. Then run claude mcp list, or /mcp inside a session, and check that koru is connected. See the Claude Code MCP docs.

bash
claude mcp list

Claude Desktop. Open Claude Desktop's config file, claude_desktop_config.json: on macOS, ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows, %APPDATA%\Claude\claude_desktop_config.json; on Linux, ~/.config/Claude/claude_desktop_config.json. Add a koru entry under mcpServers. Put the path in command (no surrounding quotes, and on Windows double every backslash, for example C:\\path\\to\\Koru\\koru-mcp.exe) and put serve and --stdio in args. Merge it with any servers already there. JSON does not allow trailing commas or comments. Quit Claude Desktop completely, including its icon in the notification area or menu bar, and open it again. In the chat, use Connectors from the + button under the box to confirm that Koru and its tools are listed. See the Claude Desktop help article.

json
{
  "mcpServers": {
    "koru": {
      "command": "/Applications/Koru.app/Contents/MacOS/koru-mcp",
      "args": ["serve", "--stdio"]
    }
  }
}

Cursor. Cursor reads MCP config from .cursor/mcp.json in a project, or from ~/.cursor/mcp.json in your home directory for every project. Add a local server with command and args. Save the file and restart Cursor. Use the same Windows or Linux path you copied from Koru. See the Cursor MCP docs.

json
{
  "mcpServers": {
    "koru": {
      "command": "/Applications/Koru.app/Contents/MacOS/koru-mcp",
      "args": ["serve", "--stdio"]
    }
  }
}

Codex and ChatGPT desktop. Codex CLI can add the server in one command:

bash
codex mcp add koru -- /Applications/Koru.app/Contents/MacOS/koru-mcp serve --stdio

You can also add a [mcp_servers.koru] entry to ~/.codex/config.toml, with command set to the binary and args set to ["serve", "--stdio"]. The ChatGPT desktop app can use the same local stdio server. In ChatGPT desktop, open Settings, then MCP servers, then Add server. Choose STDIO, enter the path to koru-mcp as the command and serve --stdio as the arguments, save, and restart. ChatGPT in a web browser does not launch a local process on your computer, so this recipe is for the desktop app. See the ChatGPT MCP docs.

toml
[mcp_servers.koru]
command = "/Applications/Koru.app/Contents/MacOS/koru-mcp"
args = ["serve", "--stdio"]

Gemini CLI. Gemini CLI reads mcpServers from ~/.gemini/settings.json (user) or .gemini/settings.json (project). You can add the server with the command below. The official default scope is the current project, so -s user is what you want if you plan to use Koru from more than one directory. See the Gemini CLI MCP docs.

bash
gemini mcp add -s user koru /Applications/Koru.app/Contents/MacOS/koru-mcp serve --stdio

The same entry can be written by hand:

json
{
  "mcpServers": {
    "koru": {
      "command": "/Applications/Koru.app/Contents/MacOS/koru-mcp",
      "args": ["serve", "--stdio"]
    }
  }
}

Once a client is connected, try a small request first: ask it to list your Koru workspaces, then to create a test document, then to open it in Koru. If a client still shows an old list of tools after you update Koru, quit the client completely so the old koru-mcp process exits, and open it again.

MCP vs API

An API is how one program talks to a specific service. Each API has its own URLs, authentication, and shapes for requests and responses. That is a good fit when you are writing code against one product.

MCP is not a replacement for APIs. It is a protocol for AI applications. A host that already speaks MCP can discover a server's tools, read their input schemas, and call them, without a custom integration for that one product. Many MCP servers, including ones that talk to issue trackers or databases, sit in front of an ordinary API. Koru's local server sits in front of Koru on your computer, not in front of a public HTTP API.

The practical difference is who the interface is for. You use an API when you are building an integration. You use an MCP server when you want the AI you already use to work with an app, through a standard set of tools, with the host handling connection and consent.

Koru also has a local HTTP API, and a Cloud API is available with Koru Cloud. Those are for scripts and applications. The MCP server is the path for Claude, Cursor and other MCP clients. Both are documented from Koru for developers.

For the copied command, the full tool reference, errors and platform notes, use Koru's built-in MCP server. For the local API and the rest of the developer surface, start at Koru for developers. If you want the notes app itself, with terminal tabs next to your documents, see notes for developers, or download Koru.

The protocol, including the official definitions of hosts, clients, servers, tools, resources, prompts and transports, is documented at modelcontextprotocol.io.

Frequently asked questions

What is an MCP server?

An MCP server is a program that exposes tools, and optionally resources and prompts, to an AI application through the Model Context Protocol. The host (Claude, Cursor, and so on) connects to the server and can then call those tools on your behalf. A local MCP server usually runs as a child process over stdio. A remote MCP server is usually reached over Streamable HTTP. Koru's built-in server, `koru-mcp`, is a local MCP server that ships with the app.

What is MCP vs API?

MCP is an open protocol that AI applications use to discover and call tools in a standard way. An API is a product-specific interface for programs to talk to that product. An MCP server often wraps an API, or wraps a local app such as Koru, so that any MCP-compatible host can use it without a one-off integration. If you are writing a script, Koru's HTTP API may be the better fit. If you want the AI you choose to read and edit your notes in a conversation, use the MCP server.

Does Koru have an MCP server?

Yes. Koru ships `koru-mcp` with the Windows, macOS and Linux apps. You connect an MCP client with the command on Koru's Welcome page. There is no plugin and no API key for the local server. The steps are on [Koru's MCP page](/developers/mcp). With Koru Cloud, Cloud MCP is also available.

Can an MCP client create documents and tasks in Koru?

Yes. A client can create a document in a workspace, including a complete body, in one step. It can also turn notes into tasks by inserting task blocks into a document and setting due dates or priorities where they belong. Koru does not expose a separate `create_task` tool, because a task is part of a document, the same way it is in the app. The client can then list open tasks, and open the document in Koru for you to review.

Do I need an API key to use Koru's MCP server?

Not for the local server. The client starts `koru-mcp` on your computer, and the bridge talks only to Koru there. You still need whatever account or subscription your AI host uses.

Which AI clients can I connect?

This guide covers Claude Code, Claude Desktop, Cursor, Codex, the ChatGPT desktop app, and Gemini CLI, because those setups are documented by their official docs and match Koru's local stdio command. Other MCP clients that can launch a local stdio server can use the same command. Connect only clients you trust: the local connection can read and edit every workspace Koru has on that computer.

Do my notes leave my computer?

Not through Koru's local server. The bridge stays on your machine. If the AI host sends tool results to a model in the cloud, that is the host's own behavior, under that product's terms. If you would rather keep prompts and notes on the machine, you can use a local model with an MCP client that supports one. Koru itself works offline; the model you choose may not.

Drafted with help from AI tools, edited and fact-checked by Steven Liechti.

  • Guides
  • MCP
  • AI agents
  • Claude Code

Subscribe to receive notifications of new posts

We'll never share your email address.

Privacy choices

Choose which optional tools Koru may use on this site. Your choice is saved in a cookie in this browser for 12 months. Privacy policy

Privacy choices

Keep you signed in, protect forms and remember your language and this choice.

Always on

PostHog and Google Analytics 4 measure page views and actions such as downloads, using cookies or local storage.

PostHog records how pages are used, with form inputs masked and private pages excluded. Needs Analytics.

Ahrefs Web Analytics measures visits and where they come from, and Google Ads measures whether our ads led to a visit or download.