Hillnote Logo

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

Endpointhttps://hillnote.com/mcp
TransportStreamable HTTP
AuthenticationOAuth sign-in with your Hillnote account — no API keys to copy or paste
Access levelsRead-only, or read & write — your assistant asks for one, and you see which before you allow it
What it reachesThe 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.md format 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.

The Cloud MCP card opened, with the MCP Server URL https://hillnote.com/mcp and a Copy button.

Claude (web and desktop)

  1. Open Settings → Connectors.
  2. Choose Add custom connector and paste the endpoint:
    https://hillnote.com/mcp
    
  3. 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.
  4. 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

  1. Open Settings → Connectors (or Apps, depending on your plan).
  2. Add a custom MCP connector with the endpoint https://hillnote.com/mcp.
  3. Complete the Hillnote sign-in when prompted, check the access level it asks for, and click Allow access.
  4. 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

ToolWhat it does
list_workspacesList the workspaces you own or collaborate on
list_collaboratorsSee who has access to a workspace
read_registryGet a workspace's full document index — IDs, paths, titles, tags, folders
read_documentRead a document, in full or by line range
search_documentsSearch titles, tags, and content across workspaces, with pagination

Show (interactive views)

ToolWhat it does
show_documentShow a document or slide deck as an interactive view
show_tableShow a sheet or database as an interactive table
show_moodboardShow 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)

ToolWhat it does
add_documentCreate a new document (markdown, slides, or moodboard)
rename_documentRename a document
move_documentMove one or more documents to another folder
delete_documentPermanently delete a document
insert_contentInsert text at a line or at the start/end
delete_contentDelete a range of lines, with optional content verification
replace_contentFind and replace text

Slides

ToolWhat it does
get_slides_story_guideAuthoring guide for writing slide content
get_slides_visual_guideAuthoring guide for styling slides

Moodboards

ToolWhat it does
get_moodboard_guideGuide for building moodboards (.moodboard.md): item types, layout, and connectors
read_moodboardRead every item and connector on a moodboard, with the board's settings
add_moodboard_itemsAdd images, document cards, videos, text and sticky notes, links, colour swatches, frames, shapes, and connectors
update_moodboard_itemsMove, resize, or edit items in place; their connectors stay attached
remove_moodboard_itemsRemove items, along with the connectors attached to them
clear_moodboardEmpty 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

ToolWhat it does
find_databasesFind every database in a workspace
get_database_configRead a database's columns and views
get_database_rowsPage through rows in order
query_database_rowsFilter and sort rows by column values
save_database_configUpdate a database's configuration

Sheets

ToolWhat it does
find_sheetsFind every sheet (CSV-backed dataset) in a workspace
get_sheetRead a sheet's columns, views, and row count
query_sheet_rowsSearch, filter, and sort rows, page by page
create_sheetCreate a new sheet
add_sheet_rowsAdd rows to a sheet
update_sheet_rowsChange cells on existing rows
delete_sheet_rowsPermanently delete rows

Libraries & playbooks

ToolWhat it does
list_librariesList your libraries, including cloud libraries shared with you
get_library_mapSee what a library or volume contains
get_library_outlineRead a library's volumes, chapters, and sections
search_librarySearch a library's sections
get_library_sectionRead one section, with a citation to paste
list_playbooksList saved playbooks: your own answers to recurring kinds of question
read_playbookRead a playbook with the sources it pins
create_playbookSave a new playbook
update_playbookEdit an existing playbook

Recipes

ToolWhat it does
list_recipesList saved prompt recipes
get_recipeRead one recipe
get_recipe_documentsFetch the documents a recipe references
create_recipeSave a new recipe
update_recipeEdit an existing recipe

HTML tools

ToolWhat it does
get_html_tool_guideAuthoring guide for HTML tools
list_html_toolsList the mini-apps in a workspace
get_html_toolRead a mini-app's files
read_html_fileRead one file, in full or by line range
add_html_toolCreate a new mini-app from a set of files
write_html_fileCreate or overwrite a file in a mini-app
replace_in_html_fileFind and replace inside a mini-app file
attach_tool_sheetGive a mini-app a sheet to save records in
attach_tool_databaseConnect a database to a mini-app
add_tool_viewShow 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.