# HackMD — how to use (mcp.ai)

Connect your HackMD account and use 8 tools for documents straight from your AI agent. Connect with your own API key. HackMD is a collaborative Markdown workspace for creating, organizing, and sharing personal and team notes.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_hackmd?ms=1787291400000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `hackmd_create_note`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/hackmd`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/hackmd/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/hackmd/create/note` — Create a Markdown note in the personal workspace or a specified team workspace. The team branch is documented but was not live-tested because the test account belongs to no teams.
  - body: { tags?: string[], title?: string, content?: string, team_path?: string, description?: string, read_permission?: string, parent_folder_id?: string, write_permission?: string, comment_permission?: string, suggest_edit_permission?: string }
- `POST https://api.mcp.ai/api/hackmd/get/account` — Return the HackMD profile for the connected token and the teams visible to it. Use the returned team paths with tools that accept team_path.
- `POST https://api.mcp.ai/api/hackmd/get/note` — Get a note by ID, including its Markdown content. The personal note route can also retrieve an accessible team note, so no team selector is needed.
  - body: { note_id: string }
- `POST https://api.mcp.ai/api/hackmd/list/folders` — List all folders in the personal workspace, or in one team workspace when team_path is supplied. Use a folder ID as parent_folder_id when creating a note. The team route is documented but was not live
  - body: { team_path?: string }
- `POST https://api.mcp.ai/api/hackmd/list/notes` — List all notes in the personal workspace, or in one team workspace when team_path is supplied. HackMD returns the complete collection without pagination; the team route is documented but was not live-
  - body: { team_path?: string }
- `POST https://api.mcp.ai/api/hackmd/list/trash` — List soft-deleted notes in the personal workspace. Team trash is intentionally excluded because it requires team-admin permission and could not be live-tested.
- `POST https://api.mcp.ai/api/hackmd/move/note/to/trash` — Soft-delete a note by moving it to trash in the personal workspace or an explicitly selected team workspace. This is not permanent deletion. Personal notes can be restored with HACKMD_RESTORE_NOTES; t
  - body: { note_id: string, team_path?: string }
- `POST https://api.mcp.ai/api/hackmd/restore/notes` — Restore one or more personal notes from HackMD trash. Returns a per-note success or failure outcome so a partial HTTP 207 result is never reported as an unconditional success.
  - body: { note_ids: string[] }

## Example prompts
- "What can I do in HackMD?"
- "Show me a summary of my HackMD account"

## More
- Page: https://mcp.ai/hackmd
- Agent spec (llms.txt): https://mcp.ai/hackmd/llms.txt
- Postman collection: https://mcp.ai/hackmd/postman.json