Bug: create-a-comment (POST /v1/comments) 400s with missing_version — only op missing Notion-Version param after #320

[derrickshowers]

Summary

create-a-comment (POST /v1/comments) always fails with HTTP 400 missing_version ("Notion-Version header should be defined"). It is the only operation in the bundled OpenAPI spec that is missing its Notion-Version header parameter, so the server sends the request with no version header.

• Package version: @notionhq/notion-mcp-server@2.4.1
• Auth: NOTION_TOKEN (stdio) — but this is auth-independent; it reproduces regardless.

Root cause

Since #320 ("source Notion-Version per operation"), HttpClient.buildDefaultHeaders() derives Notion-Version from each operation's header-parameter default in scripts/notion-openapi.json. That works only if the operation actually declares the parameter.

In the shipped spec, every operation references the shared param except create-a-comment, whose parameters array is empty:

// GET /v1/comments  (retrieve-a-comment) — correct
"parameters": [ /* …query params… */, { "$ref": "#/components/parameters/notionVersion" } ]

// POST /v1/comments (create-a-comment) — BUG: no Notion-Version
"parameters": []

The shared component is present and fine:

"#/components/parameters/notionVersion": {
  "name": "Notion-Version", "in": "header", "required": false,
  "schema": { "type": "string", "default": "2025-09-03" },
  "description": "The Notion API version"
}

I scanned the whole spec: 24 operations, exactly 1 missing the param — POST /v1/comments. Even GET /v1/comments has it, so this looks like an oversight in #320 rather than intentional.

Reproduction

1. Configure the server with any valid integration token.
2. Call API-create-a-comment with a valid parent.page_id + rich_text.
3. Notion responds 400 / code: "missing_version".

(API-patch-block-children, API-retrieve-a-comment, etc. all work — they carry the version.)

Fix

Add the shared param to the create-a-comment operation in scripts/notion-openapi.json:

   "/v1/comments": {
     "post": {
       "operationId": "create-a-comment",
-      "parameters": []
+      "parameters": [
+        { "$ref": "#/components/parameters/notionVersion" }
+      ]

Workaround (for others hitting this)

Set a global version, which buildDefaultHeaders lets win for every operation:

"OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_…\",\"Notion-Version\":\"2025-09-03\"}"

[kmccammon]

Confirming this still reproduces on 2.5.1 (current latest, published 2026-07-25) — so the regression has now shipped through two further releases (2.5.0, 2.5.1) while #329 has been open and mergeable.

Verified independently against the installed spec, same root cause as described above:

operations with NO Notion-Version param (inline or $ref): 1
    create-a-comment  POST /v1/comments

POST /v1/comments has no parameters array at all, so buildDefaultHeaders() emits nothing and the request goes out unversioned. GET /v1/comments carries the $ref and works fine, which makes the failure look auth- or permission-shaped at first — reading comments succeeds and writing them 400s with the same token.

Also worth noting for anyone hitting this: the obvious workaround of pinning Notion-Version globally via OPENAPI_MCP_HEADERS is a trap. Configured headers take precedence over the per-operation defaults, so a global 2025-09-03 also overrides the two page-markdown operations that pin 2026-03-11. It fixes comments and quietly breaks those.

Local one-line patch to scripts/notion-openapi.json pending #329:

"operationId": "create-a-comment",
"parameters": [
  { "$ref": "#/components/parameters/notionVersion" }
],