Hillnote MCP Server
Connect AI assistants to your Hillnote workspaces. Hillnote exposes a remote Model Context Protocol (MCP) server, so Claude, ChatGPT, Cursor, and any other MCP-compatible client can search, read, and edit the documents you already own — with your permission, over a secure sign-in.
At a glance
| Endpoint | https://hillnote.com/mcp |
| Transport | Streamable HTTP |
| Authentication | OAuth sign-in with your Hillnote account — no API keys to copy or paste |
| Access levels | Read-only, or read & write — your assistant asks for one, and you see which before you allow it |
| What it reaches | The workspaces you've synced to Hillnote (owned and shared with you) |
What you can do
Once connected, your assistant can work with your workspace the way you do:
- Ask questions about your notes. Search across titles, tags, and content in every workspace, then read the documents that matter — answers grounded in what you actually wrote.
- Create and edit documents. Draft new notes, insert or rewrite sections, rename, move, and organize — the assistant edits the same markdown files you see in the app.
- Build slide decks. Hillnote's
.slides.mdformat turns markdown into presentations; the assistant follows built-in authoring guides to write the story first, then style it. - Build moodboards. Pin images, notes, links, videos, and colour swatches to a moodboard (
.moodboard.md), grouped in frames and joined by connectors. - Query your databases. Hillnote databases are folders of markdown rows; the assistant can filter, sort, and paginate them like a table.
- Use and manage recipes. Recipes are saved prompt templates with reference documents; assistants can run them, create new ones, and keep them up to date.
- Create HTML tools. Ask for a calculator, tracker, or visualization and the assistant builds a self-contained mini-app right in your workspace.
- See it right in the chat. In apps that support interactive connectors, the assistant can show a document, slide deck, sheet, database or moodboard as a live view in the conversation. See Interactive views below.
Interactive views
In apps that support interactive connectors (such as Claude on the web, desktop and mobile), Hillnote shows your work inside the conversation instead of describing it. Ask to see something, like “show me my launch deck”, “show the Sales database” or “open my brand moodboard”, and the assistant opens a view:
- Documents are rendered with their headings, images, tables and code. Expand the view to read the whole document; links to other documents open in the same view, with a Back button.
- Slide decks open in a deck viewer. Use the previous and next buttons or the arrow keys.
- Sheets and databases start as a preview card. Expand it into a table you can search, sort, filter by status and page through.
- Moodboards show the whole board, scaled to fit. Expanded, drag to pan, and pinch or hold Ctrl (⌘ on a Mac) and scroll to zoom.
Every view has Open in Hillnote, which opens the same page in the desktop app. If you use the web app at app.hillnote.com, Open on the web opens it there. On a phone, the view links to the web app.
The views are read-only. To change something, ask the assistant; it edits with the regular tools. Apps without interactive connectors, such as Claude Code, get a short text summary instead.
Views follow your app's light or dark theme. Images come from your workspace through private links that expire after 15 minutes.
Connect your assistant
In the Hillnote app, the Cloud MCP card in Settings → Connections shows the endpoint, https://hillnote.com/mcp, with a Copy button.

Claude (web and desktop)
- Open Settings → Connectors.
- Choose Add custom connector and paste the endpoint:
https://hillnote.com/mcp - Click Connect. Your browser opens a Hillnote sign-in — log in, check whether Claude asks for read-only or read & write access, then click Allow access.
- Back in Claude, start a chat and ask it to “list my Hillnote workspaces” to confirm everything is wired up.
Using Claude? Install the free Hillnote skill too — a small instruction pack that teaches Claude Hillnote's formats and tools, and makes this connector noticeably sharper.
ChatGPT
- Open Settings → Connectors (or Apps, depending on your plan).
- Add a custom MCP connector with the endpoint
https://hillnote.com/mcp. - Complete the Hillnote sign-in when prompted, check the access level it asks for, and click Allow access.
- Ask ChatGPT to list your workspaces to confirm the connection.
Cursor, and any other MCP client
Any client that supports remote MCP servers over Streamable HTTP with OAuth can connect. Point it at:
https://hillnote.com/mcp
The client will discover Hillnote's sign-in automatically (OAuth 2.1 with PKCE and dynamic client registration — no manual configuration needed). When the browser opens, log in to Hillnote and authorize.
Working locally instead? The Hillnote desktop app also bundles a local MCP server that operates on the files on your machine, with no sync or sign-in required. Find it under Settings → Connections in the app.
How access works
You sign in — you don't paste keys. Connecting an assistant opens a standard Hillnote sign-in in your browser. Nothing is shared until you approve, and there's no long-lived API key that can leak.
You see the access level before you allow it. Your assistant asks for one of two levels, and the sign-in page shows which before you click Allow access or Deny:
- Read-only — the assistant can list, search, and read, but cannot change anything.
- Read & write — the assistant can also create, edit, move, and delete documents.
Access follows your workspace permissions. An assistant connected to your account can only reach workspaces you own or have been invited to collaborate on — the same boundaries that apply when you use Hillnote yourself.
Every change is logged. Edits made through MCP appear in the workspace sync log, attributed to the connected client (for example, “via Claude”).
Disconnect any time. Remove Hillnote from your assistant's connectors. Access tokens are short-lived: they expire after 24 hours, and your assistant renews them while it stays connected.
Tool reference
The server exposes more than 50 tools. Read tools never modify anything; write tools require a read & write connection.
Discover & read
| Tool | What it does |
|---|---|
list_workspaces | List the workspaces you own or collaborate on |
list_collaborators | See who has access to a workspace |
read_registry | Get a workspace's full document index — IDs, paths, titles, tags, folders |
read_document | Read a document, in full or by line range |
search_documents | Search titles, tags, and content across workspaces, with pagination |
Show (interactive views)
| Tool | What it does |
|---|---|
show_document | Show a document or slide deck as an interactive view |
show_table | Show a sheet or database as an interactive table |
show_moodboard | Show a moodboard as an interactive board |
The views also use three tools of their own, render_document, render_moodboard and get_asset_urls, to load what they draw. Apps hide these from the assistant.
Documents (write)
| Tool | What it does |
|---|---|
add_document | Create a new document (markdown, slides, or moodboard) |
rename_document | Rename a document |
move_document | Move one or more documents to another folder |
delete_document | Permanently delete a document |
insert_content | Insert text at a line or at the start/end |
delete_content | Delete a range of lines, with optional content verification |
replace_content | Find and replace text |
Slides
| Tool | What it does |
|---|---|
get_slides_story_guide | Authoring guide for writing slide content |
get_slides_visual_guide | Authoring guide for styling slides |
Moodboards
| Tool | What it does |
|---|---|
get_moodboard_guide | Guide for building moodboards (.moodboard.md): item types, layout, and connectors |
read_moodboard | Read every item and connector on a moodboard, with the board's settings |
add_moodboard_items | Add images, document cards, videos, text and sticky notes, links, colour swatches, frames, shapes, and connectors |
update_moodboard_items | Move, resize, or edit items in place; their connectors stay attached |
remove_moodboard_items | Remove items, along with the connectors attached to them |
clear_moodboard | Empty a moodboard to start over (needs confirmation) |
To make a board, call add_document with a title ending in .moodboard.md and no content, then fill it with add_moodboard_items. The text-editing tools don't work on moodboards, and read_document gives only a summary of one, so use read_moodboard. See Moodboards.
Databases
| Tool | What it does |
|---|---|
find_databases | Find every database in a workspace |
get_database_config | Read a database's columns and views |
get_database_rows | Page through rows in order |
query_database_rows | Filter and sort rows by column values |
save_database_config | Update a database's configuration |
Sheets
| Tool | What it does |
|---|---|
find_sheets | Find every sheet (CSV-backed dataset) in a workspace |
get_sheet | Read a sheet's columns, views, and row count |
query_sheet_rows | Search, filter, and sort rows, page by page |
create_sheet | Create a new sheet |
add_sheet_rows | Add rows to a sheet |
update_sheet_rows | Change cells on existing rows |
delete_sheet_rows | Permanently delete rows |
Libraries & playbooks
| Tool | What it does |
|---|---|
list_libraries | List your libraries, including cloud libraries shared with you |
get_library_map | See what a library or volume contains |
get_library_outline | Read a library's volumes, chapters, and sections |
search_library | Search a library's sections |
get_library_section | Read one section, with a citation to paste |
list_playbooks | List saved playbooks: your own answers to recurring kinds of question |
read_playbook | Read a playbook with the sources it pins |
create_playbook | Save a new playbook |
update_playbook | Edit an existing playbook |
Recipes
| Tool | What it does |
|---|---|
list_recipes | List saved prompt recipes |
get_recipe | Read one recipe |
get_recipe_documents | Fetch the documents a recipe references |
create_recipe | Save a new recipe |
update_recipe | Edit an existing recipe |
HTML tools
| Tool | What it does |
|---|---|
get_html_tool_guide | Authoring guide for HTML tools |
list_html_tools | List the mini-apps in a workspace |
get_html_tool | Read a mini-app's files |
read_html_file | Read one file, in full or by line range |
add_html_tool | Create a new mini-app from a set of files |
write_html_file | Create or overwrite a file in a mini-app |
replace_in_html_file | Find and replace inside a mini-app file |
attach_tool_sheet | Give a mini-app a sheet to save records in |
attach_tool_database | Connect a database to a mini-app |
add_tool_view | Show a mini-app as a Custom view of a database or sheet |
Limits
These keep connections fast and conversations focused:
- Search, document reads, and database queries are paginated — assistants fetch ranges instead of entire workspaces, and responses tell them how to get the next page.
- Tool responses are capped at 100 KB; oversized results return a preview with instructions to fetch a specific range.
- Individual writes are capped at 10 MB.
- Bulk moves handle up to 25 documents per call.
- Requests are rate-limited to 300 per 15 minutes per connection.
Troubleshooting
“Workspace not found” or an empty workspace list.
The MCP server reaches synced workspaces. Open the Hillnote app and sync the workspace first, then ask the assistant to list workspaces again.
The assistant says it can't edit anything.
The connection likely has read-only access. Disconnect and connect again, and check that the sign-in page asks for read & write access before you click Allow access. The level comes from your assistant, so if it only ever asks for read-only, it can't make changes.
The sign-in window never appears.
Pop-up blockers can swallow the OAuth window — allow pop-ups for your assistant and retry. If you're behind a corporate proxy, make sure hillnote.com is reachable.
Search results seem incomplete on a huge workspace.
Content search scans the most recently modified documents first and tells the assistant when results are partial. Asking with a more specific query, or naming the workspace, narrows the scan.
A connection stopped working after a while.
Tokens expire after 24 hours; most clients refresh automatically. If yours didn't, disconnect and reconnect once.
Privacy & security
- All traffic is HTTPS; authorization uses OAuth 2.1 with PKCE.
- Documents are only accessed when a tool is called in your conversation — there is no background indexing or training on your content.
- File paths are validated server-side; assistants cannot reach outside your workspaces.
- See our Privacy Policy for the full picture of what we store and for how long.
Questions?
Reach us at [email protected] — or ask your newly connected assistant to draft the email in your workspace. It can do that now.