notion-mcp-server 2.6.1 → 2.7.0

package/README.md

@@ -26,6 +26,7 @@ An agent-first **Notion MCP server** (Model Context Protocol) that connects Clau
   - [Claude Code / Cursor / Claude Desktop](#claude-code--cursor--claude-desktop)
   - [Docker / Podman / OrbStack](#docker--podman--orbstack)
   - [Optional `NOTION_PAGE_ID`](#optional-notion_page_id)
+- [Remote / HTTP transport](#-remote--http-transport)
 - [Features: what this Notion MCP server does](#-features-what-this-notion-mcp-server-does)
 - [MCP tools for Notion (`notion_execute` & `notion_describe`)](#-mcp-tools-for-notion-notion_execute--notion_describe)
   - [`notion_execute`](#notion_execute)
@@ -388,6 +389,49 @@ claude mcp add notion -s user \
 
 ---
 
+## 🌐 Remote / HTTP transport
+
+By default the server speaks **stdio** (the local connector path above). To run it as a remote/hosted endpoint — for web clients, networked agents, or a shared deployment — set `MCP_TRANSPORT=http`:
+
+```bash
+MCP_TRANSPORT=http PORT=3000 NOTION_TOKEN=ntn_xxx npx -y notion-mcp-server
+# -> notion-mcp-server vX.Y.Z running on http://127.0.0.1:3000/mcp
+```
+
+It serves the MCP **Streamable HTTP** protocol at `POST/GET/DELETE /mcp` (stateful sessions via the `mcp-session-id` header) plus an unauthenticated `GET /health`. It's **single-tenant** — every request uses the one `NOTION_TOKEN` the process was started with.
+
+### Configuration
+
+| env | default | meaning |
+| --- | --- | --- |
+| `MCP_TRANSPORT` | `stdio` | set to `http` to enable the HTTP transport |
+| `PORT` | `3000` | listen port (`0` = OS-assigned) |
+| `HOST` | `127.0.0.1` | bind address. Loopback by default; set `0.0.0.0` to expose externally (do this only with `MCP_AUTH_TOKEN`) |
+| `MCP_AUTH_TOKEN` | — | when set, every `/mcp` request must send `Authorization: Bearer <token>` |
+| `MCP_ALLOWED_HOSTS` | localhost + bound host | comma-list for DNS-rebinding `Host` allowlist |
+| `MCP_ALLOWED_ORIGINS` | localhost origins | comma-list for browser `Origin` allowlist |
+
+> ⚠️ **Single-tenant means whoever reaches `/mcp` acts as your `NOTION_TOKEN`.** On loopback (the default) that's just local processes. Before binding a non-loopback `HOST`, set `MCP_AUTH_TOKEN` (the server logs a warning if you don't) and/or put it behind an authenticating reverse proxy.
+
+### Try it
+
+```bash
+# health check
+curl http://127.0.0.1:3000/health
+# -> {"status":"healthy","transport":"http","port":3000}
+
+# point the MCP Inspector at it
+npx @modelcontextprotocol/inspector --transport http --server-url http://127.0.0.1:3000/mcp
+```
+
+In Docker, set the env and publish the port:
+
+```bash
+docker run --rm -e NOTION_TOKEN=ntn_xxx -e MCP_TRANSPORT=http -p 3000:3000 ghcr.io/awkoy/notion-mcp-server
+```
+
+---
+
 ## 🌟 Features: what this Notion MCP server does
 
 - **Two-tool surface** — `notion_execute` (do it) + `notion_describe` (learn the shape). The whole API is one schema deep.

package/build/config/http.js

@@ -0,0 +1,29 @@
+const DEFAULT_PORT = 3000;
+const DEFAULT_HOST = "127.0.0.1";
+function parseList(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/** Pure: derive the transport config from environment variables. No I/O.
+ *
+ *  `allowedHosts`/`allowedOrigins` are returned as the *explicit* env lists only
+ *  (empty when unset). The localhost defaults depend on the actually-bound port —
+ *  which can differ from `port` when `PORT=0` — so they are filled in by startHttp
+ *  after the socket is listening, not here. */
+export function parseHttpConfig(env) {
+    const transport = (env.MCP_TRANSPORT ?? "").trim().toLowerCase() === "http" ? "http" : "stdio";
+    const portRaw = (env.PORT ?? "").trim();
+    const portNum = Number.parseInt(portRaw, 10);
+    // 0 is valid — it asks the OS for an ephemeral port. Negatives/NaN -> default.
+    const port = Number.isInteger(portNum) && portNum >= 0 ? portNum : DEFAULT_PORT;
+    const host = (env.HOST ?? "").trim() || DEFAULT_HOST;
+    const authTokenRaw = (env.MCP_AUTH_TOKEN ?? "").trim();
+    const authToken = authTokenRaw === "" ? undefined : authTokenRaw;
+    const allowedHosts = parseList(env.MCP_ALLOWED_HOSTS);
+    const allowedOrigins = parseList(env.MCP_ALLOWED_ORIGINS);
+    return { transport, port, host, authToken, allowedHosts, allowedOrigins };
+}

package/build/index.js

@@ -1,10 +1,21 @@
 #!/usr/bin/env node
-import { startServer } from "./server/index.js";
-import { registerAllTools } from "./tools/index.js";
+import { initOperations } from "./operations/index.js";
+import { parseHttpConfig } from "./config/http.js";
+import { startStdio } from "./server/index.js";
 async function main() {
     try {
-        await registerAllTools();
-        await startServer();
+        // Populate the global operation registry once, before any server instance
+        // is built (the HTTP transport builds one server per session).
+        await initOperations();
+        const config = parseHttpConfig(process.env);
+        if (config.transport === "http") {
+            // Lazy import so the stdio path never loads the HTTP stack.
+            const { startHttp } = await import("./server/http.js");
+            await startHttp(config);
+        }
+        else {
+            await startStdio();
+        }
     }
     catch (error) {
         console.error("Unhandled server error:", error instanceof Error ? error.message : String(error));

package/build/prompts/index.js

@@ -1,5 +1,4 @@
 import { z } from "zod";
-import { server } from "../server/index.js";
 function userMessage(text) {
     return {
         messages: [
@@ -10,7 +9,7 @@ function userMessage(text) {
         ],
     };
 }
-export function registerAllPrompts() {
+export function registerAllPrompts(server) {
     server.registerPrompt("create_task", {
         title: "Create Notion task",
         description: "Create a new task page in Notion with optional status and due date.",

package/build/server/auth.js

@@ -0,0 +1,36 @@
+import { timingSafeEqual } from "node:crypto";
+function bearerToken(headers) {
+    const raw = headers["authorization"] ?? headers["Authorization"];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    if (!value)
+        return null;
+    const parts = value.trim().split(/\s+/);
+    if (parts.length !== 2 || parts[0].toLowerCase() !== "bearer")
+        return null;
+    return parts[1];
+}
+function constantTimeEqual(a, b) {
+    // timingSafeEqual requires equal-length buffers; differing lengths are a
+    // mismatch by definition (the length leak is acceptable and standard).
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}
+/**
+ * Gate an HTTP request against the optional bearer token.
+ * - No token configured  -> open (ok).
+ * - Token configured, header missing/malformed -> 401.
+ * - Token configured, value mismatch            -> 403.
+ */
+export function checkAuth(headers, expectedToken) {
+    if (!expectedToken)
+        return { ok: true };
+    const provided = bearerToken(headers);
+    if (provided === null) {
+        return { ok: false, status: 401, message: "Unauthorized: missing bearer token" };
+    }
+    if (!constantTimeEqual(provided, expectedToken)) {
+        return { ok: false, status: 403, message: "Forbidden: invalid bearer token" };
+    }
+    return { ok: true };
+}

package/build/server/http.js

@@ -0,0 +1,202 @@
+import http from "node:http";
+import { randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { CONFIG } from "../config/index.js";
+import { createServer, logAccessSummary, verifyNotionAuth } from "./index.js";
+import { checkAuth } from "./auth.js";
+const MAX_BODY_BYTES = 4 * 1024 * 1024; // 4 MB
+class BodyError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+function readJsonBody(req) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                reject(new BodyError(413, "Request body too large"));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            const raw = Buffer.concat(chunks).toString("utf8");
+            if (raw.trim() === "")
+                return resolve(undefined);
+            try {
+                resolve(JSON.parse(raw));
+            }
+            catch {
+                reject(new BodyError(400, "Invalid JSON body"));
+            }
+        });
+        req.on("error", reject);
+    });
+}
+/** Discard any remaining request body and resolve once it's fully consumed. */
+function drain(req) {
+    if (req.readableEnded || req.destroyed)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        req.on("end", resolve);
+        req.on("close", resolve);
+        req.on("error", () => resolve());
+        req.resume();
+    });
+}
+async function sendJsonRpcError(req, res, status, code, message) {
+    // Fully drain the request body before responding. Ending the response while the
+    // client is still streaming the body resets the socket (ECONNRESET) and the client
+    // never sees our status — so we wait for the upload to finish first.
+    await drain(req);
+    if (res.headersSent || res.writableEnded || res.destroyed)
+        return;
+    const payload = JSON.stringify({ jsonrpc: "2.0", error: { code, message }, id: null });
+    // Connection: close — we rejected this request without reusing the socket; some
+    // keep-alive clients (Node's undici fetch) otherwise RST when they get an early
+    // response while still uploading the body. Explicit length avoids chunked framing.
+    res.writeHead(status, {
+        "content-type": "application/json",
+        "content-length": Buffer.byteLength(payload),
+        connection: "close",
+    });
+    res.end(payload);
+}
+function isLoopbackHost(host) {
+    return (host === "127.0.0.1" ||
+        host === "localhost" ||
+        host === "::1" ||
+        host === "[::1]");
+}
+/** Localhost Host-header allowlist for DNS-rebinding protection, using the
+ *  actually-bound port (handles PORT=0). Used when MCP_ALLOWED_HOSTS is unset. */
+function defaultAllowedHosts(host, port) {
+    const names = new Set(["127.0.0.1", "localhost", "[::1]", host]);
+    const out = [];
+    for (const n of names)
+        out.push(n, `${n}:${port}`);
+    return out;
+}
+function defaultAllowedOrigins(port) {
+    return ["127.0.0.1", "localhost", "[::1]"].map((h) => `http://${h}:${port}`);
+}
+export async function startHttp(config) {
+    // One transport per session; the connected server instance lives behind it.
+    const transports = {};
+    const httpServer = http.createServer((req, res) => {
+        void handle(req, res).catch(async (err) => {
+            console.error("HTTP handler error:", err);
+            await sendJsonRpcError(req, res, 500, -32603, "Internal server error");
+        });
+    });
+    // Bind first so we know the real port (PORT=0 -> OS-assigned) before building
+    // the DNS-rebinding allowlist. Reject (don't hang) on a bind failure like EADDRINUSE.
+    await new Promise((resolve, reject) => {
+        httpServer.once("error", reject);
+        httpServer.listen(config.port, config.host, () => {
+            httpServer.removeListener("error", reject);
+            resolve();
+        });
+    });
+    const addr = httpServer.address();
+    const port = typeof addr === "object" && addr ? addr.port : config.port;
+    const allowedHosts = config.allowedHosts.length > 0
+        ? config.allowedHosts
+        : defaultAllowedHosts(config.host, port);
+    const allowedOrigins = config.allowedOrigins.length > 0
+        ? config.allowedOrigins
+        : defaultAllowedOrigins(port);
+    async function handle(req, res) {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+        const pathname = url.pathname;
+        // Liveness probe — no auth, no session.
+        if (req.method === "GET" && pathname === "/health") {
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end(JSON.stringify({ status: "healthy", transport: "http", port }));
+            return;
+        }
+        if (pathname !== "/mcp") {
+            await sendJsonRpcError(req, res, 404, -32601, "Not found");
+            return;
+        }
+        const auth = checkAuth(req.headers, config.authToken);
+        if (!auth.ok) {
+            await sendJsonRpcError(req, res, auth.status, auth.status === 401 ? -32001 : -32002, auth.message);
+            return;
+        }
+        const sessionId = req.headers["mcp-session-id"];
+        if (req.method === "POST") {
+            let body;
+            try {
+                body = await readJsonBody(req);
+            }
+            catch (e) {
+                const status = e instanceof BodyError ? e.status : 400;
+                await sendJsonRpcError(req, res, status, -32700, e instanceof Error ? e.message : "Parse error");
+                return;
+            }
+            let transport = sessionId ? transports[sessionId] : undefined;
+            if (!transport) {
+                if (!sessionId && isInitializeRequest(body)) {
+                    transport = new StreamableHTTPServerTransport({
+                        sessionIdGenerator: () => randomUUID(),
+                        onsessioninitialized: (id) => {
+                            transports[id] = transport;
+                        },
+                        enableDnsRebindingProtection: true,
+                        allowedHosts,
+                        allowedOrigins,
+                    });
+                    transport.onclose = () => {
+                        if (transport.sessionId)
+                            delete transports[transport.sessionId];
+                    };
+                    const server = createServer();
+                    await server.connect(transport);
+                }
+                else {
+                    await sendJsonRpcError(req, res, 400, -32000, "Bad Request: no valid session ID");
+                    return;
+                }
+            }
+            await transport.handleRequest(req, res, body);
+            return;
+        }
+        if (req.method === "GET" || req.method === "DELETE") {
+            const transport = sessionId ? transports[sessionId] : undefined;
+            if (!transport) {
+                await sendJsonRpcError(req, res, 400, -32000, "Bad Request: invalid or missing session ID");
+                return;
+            }
+            await transport.handleRequest(req, res);
+            return;
+        }
+        await sendJsonRpcError(req, res, 405, -32601, "Method not allowed");
+    }
+    console.error(`${CONFIG.serverName} v${CONFIG.serverVersion} running on http://${config.host}:${port}/mcp`);
+    if (!config.authToken && !isLoopbackHost(config.host)) {
+        console.error("WARNING: HTTP endpoint bound to a non-loopback host without MCP_AUTH_TOKEN — anyone who can reach it acts as your NOTION_TOKEN. Set MCP_AUTH_TOKEN.");
+    }
+    logAccessSummary();
+    verifyNotionAuth();
+    const close = () => new Promise((resolve, reject) => {
+        for (const id of Object.keys(transports)) {
+            try {
+                transports[id].close();
+            }
+            catch {
+                // best-effort
+            }
+        }
+        httpServer.closeAllConnections?.();
+        httpServer.close((err) => (err ? reject(err) : resolve()));
+    });
+    return { port, close };
+}

package/build/server/index.js

@@ -2,36 +2,62 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CONFIG } from "../config/index.js";
 import { getClient } from "../services/notion.js";
-export const server = new McpServer({
-    name: CONFIG.serverName,
-    title: CONFIG.serverTitle,
-    version: CONFIG.serverVersion,
-    websiteUrl: CONFIG.serverUrl,
-}, {
-    capabilities: {
-        tools: {},
-        prompts: {},
-    },
-    instructions: `
+import { registerAllTools } from "../tools/index.js";
+import { accessSummary } from "../operations/access.js";
+/**
+ * Build a fresh, fully-registered MCP server instance.
+ *
+ * A factory (not a module singleton) because the Streamable HTTP transport needs
+ * one server per session. `initOperations()` must have run before this is called —
+ * it populates the global operation registry that the tools read from; this factory
+ * only wires the server's tools/resources/prompts and never re-registers operations.
+ */
+export function createServer() {
+    const server = new McpServer({
+        name: CONFIG.serverName,
+        title: CONFIG.serverTitle,
+        version: CONFIG.serverVersion,
+        websiteUrl: CONFIG.serverUrl,
+    }, {
+        capabilities: {
+            tools: {},
+            prompts: {},
+            resources: {},
+        },
+        instructions: `
       MCP server for Notion.
       It is used to create, update and delete Notion entities.
     `,
-});
-export async function startServer() {
+    });
+    registerAllTools(server);
+    return server;
+}
+/** Log the operation access summary once at startup (not per session). */
+export function logAccessSummary() {
+    const s = accessSummary();
+    console.error(`Operation access: ${s.enabled}/${s.total} enabled (allow=${s.allow}; block=${s.block}${s.readOnly ? "; read-only" : ""})`);
+}
+/** Fire-and-forget Notion auth probe; logs who we connected as, never throws. */
+export function verifyNotionAuth() {
+    getClient()
+        .then((c) => c.users.me({}))
+        .then((me) => {
+        const who = "name" in me && me.name ? me.name : me.id;
+        console.error(`Notion auth OK — connected as ${who} (NOTION_TOKEN)`);
+    })
+        .catch((err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Notion auth check failed (server still running): ${msg}`);
+    });
+}
+export async function startStdio() {
     try {
+        const server = createServer();
         const transport = new StdioServerTransport();
         await server.connect(transport);
         console.error(`${CONFIG.serverName} v${CONFIG.serverVersion} running on stdio`);
-        getClient()
-            .then((c) => c.users.me({}))
-            .then((me) => {
-            const who = "name" in me && me.name ? me.name : me.id;
-            console.error(`Notion auth OK — connected as ${who} (NOTION_TOKEN)`);
-        })
-            .catch((err) => {
-            const msg = err instanceof Error ? err.message : String(err);
-            console.error(`Notion auth check failed (server still running): ${msg}`);
-        });
+        logAccessSummary();
+        verifyNotionAuth();
     }
     catch (error) {
         console.error("Server initialization error:", error instanceof Error ? error.message : String(error));

package/build/tools/index.js

@@ -1,9 +1,8 @@
 import { z } from "zod";
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { server } from "../server/index.js";
 import { readNotionResource } from "./resources.js";
-import { initOperations, getOperation } from "../operations/index.js";
-import { isOperationAllowed, operationNotAllowedError, enabledOperationNames, enabledOperations, accessSummary, } from "../operations/access.js";
+import { getOperation } from "../operations/index.js";
+import { isOperationAllowed, operationNotAllowedError, enabledOperationNames, enabledOperations, } from "../operations/access.js";
 import { dispatch } from "../dispatch/index.js";
 import { emitJsonSchema } from "../schema/emit.js";
 import { registerAllPrompts } from "../prompts/index.js";
@@ -38,8 +37,7 @@ If the payload is malformed, the error response includes the full schema + a wor
 
 Most responses are slimmed by default. Pass verbose:true inside payload (single) or per-item (batch) to get the raw Notion SDK response.`;
 const DESCRIBE_DESCRIPTION = `Return the JSON Schema and a working example for one operation. Use this BEFORE notion_execute when the payload shape is non-trivial (query filters, structured block trees, database property definitions). For simple ops, just call notion_execute — its errors carry the schema.`;
-export async function registerAllTools() {
-    await initOperations();
+export function registerAllTools(server) {
     server.registerTool("notion_execute", {
         title: "Notion Execute",
         description: EXECUTE_DESCRIPTION,
@@ -126,9 +124,7 @@ export async function registerAllTools() {
         const { mimeType, text } = await readNotionResource("database", firstVar(variables.dataSourceId));
         return { contents: [{ uri: uri.href, mimeType, text }] };
     });
-    registerAllPrompts();
-    const s = accessSummary();
-    console.error(`Operation access: ${s.enabled}/${s.total} enabled (allow=${s.allow}; block=${s.block}${s.readOnly ? "; read-only" : ""})`);
+    registerAllPrompts(server);
 }
 function renderOperationsIndex() {
     const lines = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notion-mcp-server",
-  "version": "2.6.1",
+  "version": "2.7.0",
   "type": "module",
   "bin": {
     "notion-mcp-server": "build/index.js"