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

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.
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.
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.
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.
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.
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.
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.
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.
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:
claude mcp add koru -- /Applications/Koru.app/Contents/MacOS/koru-mcp serve --stdioOn Windows, the path is the one Koru copied, for example:
claude mcp add koru -- "C:\path\to\Koru\koru-mcp.exe" serve --stdioOn Linux, use the full path in the folder you extracted, for example:
claude mcp add koru -- /home/you/koru/koru-mcp serve --stdioThe -- 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.
claude mcp listClaude 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.
{
"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.
{
"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:
codex mcp add koru -- /Applications/Koru.app/Contents/MacOS/koru-mcp serve --stdioYou 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.
[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.
gemini mcp add -s user koru /Applications/Koru.app/Contents/MacOS/koru-mcp serve --stdioThe same entry can be written by hand:
{
"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.
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.
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.
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.
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.
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.
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.
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.
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.
Related tags
- Guides
- MCP
- AI agents
- Claude Code
Subscribe to receive notifications of new posts
We'll never share your email address.
