md-log-mcp
Officialmd-log-mcp lets an AI coding agent save and manage versioned Markdown reports — with embedded images — in the hosted md-log review service.
Save/write:
save_markdowncreates or overwrites a.mdby path (force last-writer-wins), auto-creates missing folders, uploads embedded images (data_base64or localfile_path) and rewrites placeholders toasset://links; optionalcommit_message.Upload images:
upload_assetuploads one image (base64 or local file) and returns anasset://<key>reference for markdown embeds.Append:
append_to_markdownadds content to an existing file with optimistic concurrency (base_version_no, one auto-retry).Replace:
update_markdownswaps the entire content, withexpected_versionfor conflict detection or omitted for LWW.Read:
get_markdownreads the current file or any old version viaversion.History:
list_versionsshows the immutable version history newest-first (version_no, commit_message, author, timestamp, size).Delete:
delete_markdownsoft-deletes a file (requiresconfirm:true).Folders:
create_folder(mkdir -p),list_folders(full tree),list_files(folder contents).Organize:
move_markdown,move_folder,rename_folderrelocate/rename while keeping the document key, version history and annotations.Folder deletion:
delete_folderremoves an empty folder or, withcascade:true, the whole subtree.Search:
search_markdownqueries titles (substring) and body full-text, returning ranked results with bolded snippets.
Note: the schema exposes 15 tools; the README's edit_markdown and restore_version are absent from it.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@md-log-mcp Save a markdown report summarizing the bug fix in src/main.js"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 theAuthorizationheader. 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-infetch/httpare the only network layers — no web framework.PAT auth — a md-log Personal Access Token sent to the backend as
Authorization: Bearer.
Related MCP server: io.github.ymxlx/polis-protocol
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 |
| The headline tool. Create or overwrite a |
| Upload one image (reserve → presigned PUT → complete) and return an |
| Append to an existing file with optimistic concurrency (GET current → concat → conditional PUT with |
| Change PART of a file by exact literal replacement (read → apply → conditional PUT with |
| Replace a file's ENTIRE content. Pass |
| Roll a file back to an earlier |
| Read a file's content by path (materializes inline content or a presigned content URL for large docs). Pass |
| List a file's immutable version history, newest first ( |
| Soft-delete a file. Requires |
|
|
| Return the full folder tree. |
| List the documents and immediate subfolders inside a folder path. |
| Search by TITLE (substring) + BODY full-text (current versions; whole-word match, ranked, body hits include a snippet). |
| Move and/or rename a |
| Move a folder (whole subtree) under a new parent ( |
| Rename a folder in place (descendant paths rewritten server-side). |
| Delete a folder. Requires |
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 |
| yes |
| The hosted service base, including |
| yes |
| Bearer PAT. Store it securely (OS keychain) — never commit it. |
| no |
| 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 |
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 smokeConnect 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_PATis ignored in this mode.)Stateless. A fresh client + server per request; no session store (replica / autoscale friendly).
No local files. The
file_pathimage source is refused (it would read the server's disk); send images inline asdata_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/mcpConfiguration (env)
Variable | Required | Default | Notes |
| yes | — | Hosted md-log base, including |
| no |
| Bind interface. Localhost-only by default; set |
| no |
| TCP port. |
| no |
| The MCP endpoint path. |
| no | (none) | Comma-separated browser |
| no | (none) | Optional comma-separated |
| no |
| 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 todist/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).
Available Tools
15 toolsappend_to_markdownAppend to MarkdownA
Append content to the end of an existing .md file using optimistic concurrency (GET current -> concat -> PUT with base_version_no). Auto-retries once on conflict, then surfaces CONFLICT.
Inputs: path (required), content (required), commit_message.
create_folderCreate FolderA
Create a folder path, creating every missing parent segment (mkdir -p). Already-existing folders are treated as success.
Inputs: path (required).
delete_folderDelete FolderA
Delete a folder. Requires confirm:true (otherwise VALIDATION). By default only an EMPTY folder is deleted (a non-empty one is refused); pass cascade:true to soft-delete the whole subtree — every subfolder and document under it (like rm -r). Documents are soft-deleted (recoverable), but prefer move_folder/move_markdown when reorganizing.
Inputs: path (required), confirm (required), cascade.
delete_markdownDelete MarkdownA
Soft-delete a .md file. Requires confirm:true (otherwise VALIDATION). Resolves the path to a document key, then DELETE /documents/{key}.
Inputs: path (required), confirm (required).
get_markdownGet MarkdownA
Read a .md file's content by path. Pass version (a version_no from list_versions) to read an OLD immutable version instead of the current one.
Inputs: path (required), version.
list_filesList FilesA
List the documents (and immediate subfolders) inside a folder path. Omit path (or pass '' / '/') to list the ROOT folder.
Inputs: path.
list_foldersList FoldersC
Return the full folder tree.
Inputs: no named parameters.
list_versionsList VersionsA
List a .md file's immutable version history, newest first (version_no, commit_message, author, registered_at, size). Read an old version's content with get_markdown + version.
Inputs: path (required).
move_folderMove FolderA
Move a folder (with its whole subtree: documents, versions, annotations) under a new parent. new_parent_path '' or omitted = move to the root. Parent folders are auto-created. Moving a folder into its own subtree is rejected by the server.
Inputs: path (required), new_parent_path.
move_markdownMove MarkdownA
Move and/or rename a .md file: from_path -> to_path. Destination folders are auto-created (mkdir -p). The document KEEPS its identity (same document key), so its whole version history and reviewers' annotations survive the move — never re-save + delete to relocate a file. Fails if a different file already occupies to_path.
Inputs: to_path (required), from_path (required).
rename_folderRename FolderA
Rename a folder in place (descendant paths are rewritten automatically; documents, versions and annotations are untouched).
Inputs: path (required), new_name (required).
save_markdownSave MarkdownA
Save (create or overwrite) a .md file in md-log by path; missing folders are auto-created. Optionally upload embedded images as assets first and rewrite their refs to asset:// links. This is a force-write (last-writer-wins) — the headline agent tool.
Inputs: path (required), content (required), assets, commit_message.
search_markdownSearch MarkdownA
Search documents by TITLE (substring) and BODY (full-text over current versions; whole-word match, ranked, body hits carry a bolded snippet). Use it to find a prior report by its content or name.
Inputs: query (required).
update_markdownUpdate MarkdownA
Replace the content of an existing .md file. Pass expected_version for optimistic concurrency (mismatch -> CONFLICT); omit it to force last-writer-wins.
Inputs: path (required), content (required), commit_message, expected_version.
upload_assetUpload AssetA
Upload a single image as an asset (reserve -> presigned PUT -> complete) and return an 'asset://' reference you can embed in markdown image syntax: . Provide the image as EITHER
data_base64 (inline base64) OR file_path (a local file to read) — exactly one.
Inputs: path (required), filename, file_path, data_base64, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool targets a distinct operation: content manipulation, folder management, listing, search, asset upload, and concurrency control. No overlap in purpose.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., save_markdown, delete_folder, list_versions).
15 tools cover the domain comprehensively without bloat. Each tool serves a clear need for managing markdown files and folders with versioning.
Covers full CRUD for documents and folders, plus listing, search, version history, assets, and concurrency. Minor gaps: no explicit tool to restore a previous version, but that can be done via get_markdown (old version) and save_markdown.
Maintenance
Related MCP Connectors
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
MarkupBase turns AI-generated Markdown and HTML into durable, versioned artifacts that people can review and discuss. Its MCP server lets agents publish new versions, preserve contextual comments, include hosted images, and respond to feedback through secure account-linked identities, creating a clear human review boundary without requiring real-time editing.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that logs AI-assisted scientific computing sessions, capturing prompts, responses, decisions, and environment snapshots to human-readable markdown files for reproducibility.MIT
- AlicenseNot gradedqualityCmaintenanceThis MCP server provides a local-first control plane for coding agents, enabling task routing, contract management, and shared learning across multiple AI vendors via markdown files.5MIT
- AlicenseAqualityBmaintenanceA local-first MCP server that provides a shared Markdown-based memory for AI coding agents, enabling cross-agent context persistence via tools like memory_search and memory_capture.161MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that lets multiple AI coding agents share state, preserve context across sessions, and coordinate via a knowledge graph, messaging, and branch-preserving checkpoint/resume with conflict handling.57 npm1Apache 2.0