How do I install Md Log?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Md Log need an API key?

The publisher lists these environment variables: MDLOG_API_BASE_URL, MDLOG_PAT.

What transport does Md Log use?

Md Log runs locally over stdio.

When was Md Log last checked?

Last checked 2026-11-12. md-log MCP: save/update/fetch markdown by path (stdio + remote HTTP, PAT auth).

Md Log MCP server

md-log-mcp

Review the report, not the diff. An MCP server that lets your AI coding agent — Claude Code, Claude Desktop, Codex, Cursor — save its work and analysis as immutable, versioned Markdown reports into md-log, a human-in-the-loop review & archive layer for "vibe coding." You then read and stylus-annotate (S-Pen / Apple Pencil) those reports on web, phone, and tablet — every save a new immutable version.

A Model Context Protocol server — two transports, one tool set — that lets Claude Code (and other agents) save .md files — text and embedded screenshots together — straight into md-log, a human-in-the-loop review & archive layer for vibe coding. The recommended way to connect is the hosted remote endpoint (https://mcp.md-log.com/mcp, a URL + your key — no install); a local stdio (npx -y md-log-mcp) transport is the alternative. The agent writes a report by path (my-project/2026-07-07-error-report.md); missing folders are auto-created, images are uploaded and their references rewritten to asset:// links, and every save becomes an immutable new version. The same report is then readable, editable, and stylus-annotatable (S-Pen / Apple Pencil where supported) on a phone or tablet, and on the web.

md-log is a hosted service at https://app.md-log.com — you don't run any server yourself. This package is just the connector: a thin authenticated HTTP client that validates POSIX paths, orchestrates asset uploads, maps errors to stable agent codes, and forwards everything to the hosted md-log service — the single authority for auth, storage, versioning and quota. All you need is a Personal Access Token from the web app.

Stack

@modelcontextprotocol/sdk (TypeScript) — one McpServer (17 tools), two transports.
stdio transport (md-log-mcp) — JSON-RPC over stdin/stdout; the default local mode (so stdout is reserved for the protocol; logs go to stderr). PAT from env.
Streamable HTTP transport (md-log-mcp-http) — the remote mode: agents connect by URL with no local install; the PAT is taken per request from the Authorization header. See Remote (Streamable HTTP) mode.
TypeScript, bundled with tsup to ESM dist/server.js (stdio) + dist/http.js (HTTP). Runtime deps: the MCP SDK and zod (input schemas). Node's built-in fetch/http are the only network layers — no web framework.
PAT auth — a md-log Personal Access Token sent to the backend as Authorization: Bearer.

Requirements

Node 22+
A Personal Access Token (PAT) minted in the md-log web app (Settings → Tokens; shown once)

That's it — the md-log service itself is hosted at https://app.md-log.com; there is nothing to install or self-host.

Tools (17)

Every tool returns dual output — a human-readable content[].text and a machine-readable structuredContent — and validates the POSIX path (NFC-normalize; reject ../., control chars, empty/whitespace segments, backslashes, reserved names; enforce 255-byte name / 1024-byte path limits; require .md for files) before any backend call. All requests hit the base URL in MDLOG_API_BASE_URL (which already includes /api/v1).

Tool	What it does
`save_markdown` ⭐	The headline tool. Create or overwrite a `.md` by path (force last-writer-wins); missing folders auto-created. Optionally uploads embedded images first (each given as `data_base64` or a local `file_path`) and rewrites each `placeholder` in the content to an `asset://<key>` link. Accepts `commit_message` — a recommended 1-2 line change summary shown in the version history.
`upload_asset`	Upload one image (reserve → presigned PUT → complete) and return an `asset://<key>` reference to embed as `![alt](asset://<key>)`. Provide the image as either `data_base64` (inline base64) or `file_path` (a local file the server reads) — exactly one; with `file_path`, `filename` defaults to the basename and `content_type` is inferred from the extension (png/jpg/jpeg/gif/webp/avif).
`append_to_markdown`	Append to an existing file with optimistic concurrency (GET current → concat → conditional PUT with `base_version_no`). Auto-retries once on conflict, then surfaces `CONFLICT`. Accepts `commit_message` — a recommended 1-2 line change summary shown in the version history.
`edit_markdown`	Change PART of a file by exact literal replacement (read → apply → conditional PUT with `base_version_no`; auto-retries once on conflict, re-applying every edit). Pass several changes at once as `edits: [{old_string, new_string, replace_all?}, …]` (max 50, applied in order) — they land as one write = one version = one notification; for a single change the `old_string`/`new_string` shorthand still works (never both). Each `old_string` must match exactly once, counting overlapping positions too (`"\n\n"` inside `"\n\n\n"` is ambiguous → `detail.overlapping: true`) — 0 matches or an ambiguous >1 rejects the whole call with `VALIDATION` (`detail.reason` = / , = the failing edit) and ; set to change every occurrence on purpose. Other s: input shape — , , , , , (rejected before any read); result — (edits cancel out), (a step would pass the 25 MiB cap), (more occurrences replaced in one call than the document cap allows), (edits after the first stopped once the call has run 2 s — split them across calls). A match failure on the conflict retry carries . Never creates a file (missing path → ) and has no force mode — prefer it over for any partial change.

Error codes surfaced to the agent

Backend failures return { isError: true, content:[{type:"text", ...}] } with a mapped code in structuredContent.error.code:

NOT_FOUND · CONFLICT (carries the server head {server_version_no, server_checksum, …} in detail) · UNAUTHORIZED · RATE_LIMITED · QUOTA_EXCEEDED · BACKEND_UNAVAILABLE · VALIDATION · FOLDER_EXISTS (swallowed as success by create_folder) · ERROR.

Authentication

The MCP/PC lane authenticates with a Personal Access Token (mdlog_pat_…) — minted once in the web app's Settings and supplied via env. The client attaches it as Authorization: Bearer <PAT> (plus X-API-Token for compatibility) on every request. The backend is the single source of truth for auth and quota.

Variable	Required	Example	Notes
`MDLOG_API_BASE_URL`	yes	`https://app.md-log.com/api/v1`	The hosted service base, including `/api/v1`. No version suffix is appended; a trailing slash is stripped.
`MDLOG_PAT`	yes	`mdlog_pat_xxxxxxxxxxxxxxxxxxxxxxxx`	Bearer PAT. Store it securely (OS keychain) — never commit it.
`MDLOG_MAX_DOCUMENT_BYTES`	no	`26214400` (25 MiB)	Client-side pre-flight for the backend's per-document body cap, in UTF-8 bytes (Korean is 3 bytes/char). An over-cap save fails immediately with a `VALIDATION` error naming the actual size, instead of an opaque backend `400`. Applies to both transports. Change only against a self-hosted backend with a different cap.

The server fails fast at startup with a clear message if either var is missing or the base URL is malformed.

Build

npm install
npm run build      # tsup → dist/server.js (ESM, Node 22)
npm run typecheck  # tsc --noEmit (optional)

Smoke test

scripts/smoke.mjs spawns the built server over stdio (MCP SDK Client + StdioClientTransport), then runs initialize → tools/list → save_markdown (a small report embedding a tiny data: PNG) → get_markdown (reads it back, checks the marker) → search_markdown — printing PASS/FAIL per step and exiting non-zero on any failure. Run it against a live backend with a real PAT:

npm run build
MDLOG_API_BASE_URL="http://localhost:8080/api/v1" \
MDLOG_PAT="mdlog_pat_xxxx" \
node scripts/smoke.mjs        # or: npm run smoke

Connect a client

Mint the PAT in the web app's Settings → Tokens, store it securely, then add md-log to your MCP client. Never commit a PAT.

📄 연결 가이드 (HTML) — md-log.com/guides/customer-guide.html: 웹 앱에서 발급받은 MCP 키(PAT) 로 URL 연결(권장) 또는 npx 로컬 연결 (Claude Code · Desktop · Codex · Cursor).

Recommended — remote (URL), no install

Point your client at the hosted endpoint and pass the PAT as a Bearer header. Nothing to install — no Node.js, no npx. (You don't even need this package for the hosted connection.)

# Claude Code
claude mcp add --transport http md-log https://mcp.md-log.com/mcp \
  --header "Authorization: Bearer mdlog_pat_xxxxxxxxxxxxxxxxxxxxxxxx"

// Cursor / Claude Desktop / any client that takes JSON — the `type` field MUST be "http"
{
  "mcpServers": {
    "md-log": {
      "type": "http",
      "url": "https://mcp.md-log.com/mcp",
      "headers": { "Authorization": "Bearer mdlog_pat_xxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Over the remote endpoint, embed images inline (base64); uploading a local image by path (file_path) works only with the local method below.

Alternative — local (stdio via `npx`)

Runs this connector as a local subprocess (needs Node 22+; npx fetches the published package, nothing to build). Use it if you prefer a local process, need local-file (file_path) image uploads, or self-host md-log without a hosted MCP endpoint.

{
  "mcpServers": {
    "md-log": {
      "command": "npx",
      "args": ["-y", "md-log-mcp"],
      "env": {
        "MDLOG_API_BASE_URL": "https://app.md-log.com/api/v1",
        "MDLOG_PAT": "mdlog_pat_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Mint & secure the PAT. Create it in the web Settings → Tokens (it is shown only once) and keep it out of version control — prefer the OS keychain. On macOS, for example:
security add-generic-password -a "$USER" -s md-log-pat -w "mdlog_pat_xxxx"
export MDLOG_PAT="$(security find-generic-password -a "$USER" -s md-log-pat -w)"
If a PAT leaks, revoke it in the web app and mint a new one.

Remote (Streamable HTTP) mode

The second bin, md-log-mcp-http, serves the same 17 tools over MCP's Streamable HTTP transport — a single POST /mcp endpoint — so agents connect by URL with no local install. Use it when you want to host the connector centrally (a container / small VM behind a TLS reverse proxy) instead of every user running npx.

How it differs from stdio:

PAT per request. The token is not read from env; each request carries its own Authorization: Bearer <mdlog_pat_…> header, so one endpoint serves many users — each with their own md-log token. (MDLOG_PAT is ignored in this mode.)
Stateless. A fresh client + server per request; no session store (replica / autoscale friendly).
No local files. The file_path image source is refused (it would read the server's disk); send images inline as data_base64. Everything else is identical.

Run it

npm run build
MDLOG_API_BASE_URL="https://app.md-log.com/api/v1" \
node dist/http.js            # or: npm run start:http
# → md-log-mcp-http ready — POST http://127.0.0.1:8787/mcp

Configuration (env)

Variable	Required	Default	Notes
`MDLOG_API_BASE_URL`	yes	—	Hosted md-log base, including `/api/v1`.
`MDLOG_HTTP_HOST`	no	`127.0.0.1`	Bind interface. Localhost-only by default; set `0.0.0.0` only behind a TLS reverse proxy.
`MDLOG_HTTP_PORT`	no	`8787`	TCP port.
`MDLOG_HTTP_PATH`	no	`/mcp`	The MCP endpoint path.
`MDLOG_HTTP_ALLOWED_ORIGINS`	no	(none)	Comma-separated browser `Origin` allowlist (DNS-rebinding defense). A request that carries an `Origin` not on the list is `403`d; non-browser clients (no `Origin`) are always allowed.
`MDLOG_HTTP_ALLOWED_HOSTS`	no	(none)	Optional comma-separated `Host` allowlist (extra DNS-rebinding defense).
`MDLOG_HTTP_MAX_BODY_BYTES`	no	`33554432` (32 MiB)	Max request body (base64 images inflate ~33%).

Security posture (per the MCP spec): binds to 127.0.0.1 by default, requires a Bearer token on every MCP request, validates Origin against the allowlist to defeat DNS-rebinding, and caps the body size. A GET /health liveness probe (no auth) returns {"status":"ok"}. GET/DELETE on the MCP endpoint return 405 (stateless: no standalone SSE stream, no session to terminate).

Connect an agent by URL

{
  "mcpServers": {
    "md-log": {
      "type": "http",
      "url": "https://your-host.example/mcp",
      "headers": { "Authorization": "Bearer mdlog_pat_xxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Client config shape varies (Claude Code / Cursor / etc.) — the essentials are the endpoint URL and an Authorization: Bearer <PAT> header. Always terminate TLS in front of a public deployment; the PAT rides on every request.

Scripts

npm run build — bundle to dist/server.js (stdio) + dist/http.js (Streamable HTTP) (tsup, ESM, Node 22).
npm run dev — rebuild on change (tsup --watch).
npm run typecheck — tsc --noEmit.
npm run smoke — stdio smoke test against a live backend (needs env + a build).
npm run smoke:http — backend-free HTTP-transport smoke test (handshake + auth/origin/file_path guards).
npm start — run the built stdio server (node dist/server.js).
npm run start:http — run the built HTTP server (node dist/http.js).

Md Log

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Md Log?

Does Md Log need an API key?

What transport does Md Log use?

When was Md Log last checked?

Documentation

md-log-mcp

Stack

Requirements

Tools (17)

Error codes surfaced to the agent

Authentication

Build

Smoke test

Connect a client

Recommended — remote (URL), no install

Alternative — local (stdio via `npx`)

Remote (Streamable HTTP) mode

Run it

Configuration (env)

Connect an agent by URL

Scripts

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Md Log?

Does Md Log need an API key?

What transport does Md Log use?

When was Md Log last checked?

Documentation

md-log-mcp

Stack

Requirements

Tools (17)

Error codes surfaced to the agent

Authentication

Build

Smoke test

Connect a client

Recommended — remote (URL), no install

Alternative — local (stdio via npx)

Remote (Streamable HTTP) mode

Run it

Configuration (env)

Connect an agent by URL

Scripts

Alternative — local (stdio via `npx`)