hedgedoc-mcp

hedgedoc_create_note

Create a new HedgeDoc note from full Markdown content, optionally using a custom alias as its URL slug. Returns the note ID and shareable URL for viewing.

Instructions

Create a new note on the HedgeDoc instance.

Returns JSON with two fields: 'note_id' (the unique identifier / URL slug) and 'url' (the full URL where the note can be viewed or shared). Use alias to assign a human-readable slug such as 'q3-research-notes'. Notes cannot be edited afterwards: HedgeDoc 1.x has no HTTP endpoint for updating note content, so write the complete content in one call. Alias support requires FreeURL mode enabled on the server (CMD_ALLOW_FREEURL=true).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "content": "<content>"
    },
    "name": "hedgedoc_create_note"
  }
}

Input Schema

Name	Required	Description	Default
`alias`	No	Optional custom URL slug, e.g. 'meeting-2026-08-16' or 'q3-research'. Must be URL-safe (letters, digits, hyphens). Requires FreeURL mode on the server.
`content`	Yes	Full markdown content for the note. Supports standard CommonMark plus HedgeDoc extensions (diagrams, math, front matter, etc.).

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv0.2.0Oct 14, 2026

addedInput schema / properties / alias / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / alias / default
```
Added value: +null
```

changedInput schema / properties / alias / description

Previous value: -"Optional custom URL slug, e.g. 'meeting-2026-08-16' or 'q3-research'. Must be URL-safe (letters, digits, hyphens). Required if you intend to update this note later. Requires FreeURL mode on the server."New value: +"Optional custom URL slug, e.g. 'meeting-2026-08-16' or 'q3-research'. Must be URL-safe (letters, digits, hyphens). Requires FreeURL mode on the server."

addedInput schema / properties / alias / title
```
Added value: +"Alias"
```
removedInput schema / properties / alias / type
```
Removed value: -"string"
```
addedInput schema / properties / content / title
```
Added value: +"Content"
```

addedInput schema / title

Added value: +"hedgedoc_create_noteArguments"

First observedv0.1.0Aug 17, 2026

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the write/non-idempotent/open-world profile; the description adds the non-obvious consequences: notes are immutable after creation (HedgeDoc 1.x has no update HTTP endpoint) and alias creation depends on a server config flag. It also discloses the response shape, which the annotations do not cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose, then return fields, then the two caveats, which is good ordering. It loses a point for restating the alias/FreeURL constraint that the schema already carries and for running somewhat long with six sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema present, the description compensates by enumerating the returned fields (note_id, url). Combined with the immutability warning and the alias prerequisite, an agent has everything required to call this correctly in one shot.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% – both parameters already document their type, format, and the FreeURL requirement. The description's 'human-readable slug such as q3-research-notes' is only a marginal addition over the schema's own example, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource: 'Create a new note on the HedgeDoc instance.' All four siblings (read_note, note_info, whoami, list_history) are read operations, so the write verb alone separates this tool cleanly from alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives operative context: content must be complete in one call because there is no update endpoint, and the alias feature requires FreeURL mode server-side. It does not name a sibling alternative or state when not to use the tool, but for a create-only API the guidance an agent needs is present.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server