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 — you choose when you authorize |
| 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. - Sketch on canvases. Add shapes, text, and arrows to Excalidraw canvases (
.canvas.md) for diagrams and visual planning. - 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.
Connect your assistant
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 and choose the access level (read-only or read & write).
- Back in Claude, start a chat and ask it to “list my Hillnote workspaces” to confirm everything is wired up.
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 and pick your access level.
- 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 → MCP 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 choose the access level. During authorization you grant either:
- Read — 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”).
Revoke any time. Disconnect from your assistant's settings, or revoke the connection from your Hillnote account settings. Access tokens are short-lived and expire on their own within 24 hours regardless.
Tool reference
The server exposes 34 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 |
Documents (write)
| Tool | What it does |
|---|---|
add_document | Create a new document (markdown, slides, or canvas) |
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 & canvas
| Tool | What it does |
|---|---|
get_slides_story_guide | Authoring guide for writing slide content |
get_slides_visual_guide | Authoring guide for styling slides |
get_canvas_guide | Layout guide for Excalidraw canvases |
add_canvas_elements | Add shapes, text, arrows, and lines to a canvas |
clear_canvas | Empty a canvas to start over |
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 |
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 |
|---|---|
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 |
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 publish/sync the workspace first, then ask the assistant to list workspaces again.
The assistant says it can't edit anything.
You likely authorized with read-only access. Disconnect and reconnect, choosing read & write during sign-in.
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.