md-log — MCP Key Connection Guide (for customers)

Q: Do I need to install anything?

The remote (URL) method needs nothing installed — connect with just the URL and your key (recommended). The local (npx) method only needs Node.js; npx fetches and runs the connector automatically on first use, so there is no separate install or build.

Q: How do I change or revoke a key?

In the web app under Settings → Tokens you can revoke the old key and issue a new one. After getting a new key, replace the MDLOG_PAT value in your settings and restart the client.

1 What you need to connect

You need the two things below. Both can be found or issued in the md-log web app, and they are all you need to connect.

MCP keya long string starting with mdlog_pat_ — e.g. mdlog_pat_3f9a… (treat it like a password)

Connection URLhttps://mcp.md-log.com/mcp (remote URL connection — recommended)

Service URL (local method only)https://app.md-log.com/api/v1 (the MDLOG_API_BASE_URL for the local npx method)

No key yet? Issue one yourself in the web app under Settings → Tokens. The service URL is fixed to the value above (https://app.md-log.com/api/v1). The key is shown only once at issue time, so store it somewhere safe.

2 Connect the client you use

There are two ways to connect — pick one from the tabs below. Either way, you only swap MDLOG_PAT (the MCP key) for your own issued value.

Connect with a single URL — nothing to install. No Node.js, no npx. Just give your client the URL + your key (Bearer header).

Claude Code (terminal)

bash

claude mcp add --transport http md-log https://mcp.md-log.com/mcp \
  --header "Authorization: Bearer mdlog_pat_your_key_here"

Cursor · Claude Desktop · others (JSON)

Add it to ~/.cursor/mcp.json · claude_desktop_config.json · a project .mcp.json, etc.

json

{
  "mcpServers": {
    "md-log": {
      "type": "http",
      "url": "https://mcp.md-log.com/mcp",
      "headers": { "Authorization": "Bearer mdlog_pat_your_key_here" }
    }
  }
}

The type field must be http (omitting it is read as stdio). Over the remote endpoint, embed images inline (base64) — uploading a local image by file path works only with the local (npx) method.

First the local method needs Node.js 22+ — npx fetches and runs the connector automatically, so there's nothing to install by hand. Use this method if you need local-file image uploads. Check your version: node -v (v22.x+ is OK; if lower, install the LTS from nodejs.org).

① Claude Code (terminal)

bash

claude mcp add md-log \
  --scope user \
  --env MDLOG_API_BASE_URL=https://app.md-log.com/api/v1 \
  --env MDLOG_PAT=mdlog_pat_your_key_here \
  -- npx -y md-log-mcp

After registering, check with claude mcp list, and during chat use /mcp to see the status.

② Claude Desktop (desktop app)

Open the config file, add an mcpServers entry, then fully quit and relaunch the app.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

json

{
  "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_your_key_here"
      }
    }
  }
}

Once connected, the tool list appears in the tools (🔌) menu of the input box.

③ OpenAI Codex (terminal)

Add the block below to ~/.codex/config.toml (the format is TOML, not JSON).

toml

# ~/.codex/config.toml
[mcp_servers.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_your_key_here" }

Recent versions also support the codex mcp add md-log --env … -- npx -y md-log-mcp command.

④ Cursor

Settings → MCP → Add new server, or add it to ~/.cursor/mcp.json.

json

{
  "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_your_key_here"
      }
    }
  }
}

When a green dot appears in Settings → MCP, the connection succeeded.

⑤ Other MCP clients

Most work the same way — just provide the run command + 2 environment variables.

text

command : npx
args    : -y  md-log-mcp
env     : MDLOG_API_BASE_URL = https://app.md-log.com/api/v1
          MDLOG_PAT          = mdlog_pat_your_key_here

3 Verify the connection

Restart the client (to apply the settings change).
Check that md-log shows as connected in the tool list. (Claude Code: /mcp)
Ask the AI in plain language — see the examples in §4.

Success If you say something like “search my documents for ‘last week's report’” and results come back, it is connected properly.

4 Examples & automation

Once connected, just ask the AI as you normally would. For example:

📝 “Save this analysis as reports/weekly/2026-W26.md.”

➕ “Append a conclusion section to the document you just made.”

🔎 “Find reports that mention ‘conversion rate’ in my documents.”

📂 “Show me what files are in the reports folder.”

🗂 “Move last year's reports into the archive/2025 folder to tidy up.”

🕘 “Show this document's version history, and compare it with the version two back.”

What it can do: save / edit / append markdown by path, read, delete, move & rename (preserving history and annotations), view version history & read past versions, create / move / rename / delete / list folders, full-text search, and attach images. Folders are created automatically on save.

Auto-save via a rules file (no explicit instruction)

You don't have to say “save it” every time. Write the rule once in your agent's rules file (claude.md/CLAUDE.md for Claude Code, AGENTS.md for Codex, project rules for Cursor), and your agent will automatically create a .md report and save it to md-log whenever it finishes a task or analysis. Missing folders are created automatically by path, images are uploaded too, and every save accumulates as an immutable version.

Example — add a rule like this to your rules file:

claude.md

## Work log rule (md-log)
- After finishing a meaningful task or analysis, write a report summarizing "what · why · what impact".
- Save that report via the md-log MCP save_markdown at this path:
    <project>/<YYYY-MM-DD>-<topic>.md
- For large changes, include the reason, scope of impact, and follow-ups (TODO) — for review & onboarding.
- When the user gives feedback, apply it and keep logging in the same document.

Your workflow is then automated like this:

① When your agent finishes a task it writes a report (.md) → ② saves it to md-log by path (folders auto-created) → ③ review & annotate right away on web · mobile · tablet → ④ give feedback and it keeps logging & syncing in the same document.

Tip Since every task accumulates automatically, days later or on another device you can reopen “what did I do last week”, or hand a project's history straight to a new teammate or new agent. It fits a human-in-the-loop flow where a person reviews report by report instead of reading every diff.

5 Key security

Important Your MCP key (mdlog_pat_…) is like a password. Don't expose it in screen shares, screenshots, chat, or public repositories.

Don't write the key directly in config files shared with others; where possible, manage it through your own machine's environment variables.
If your key is exposed, revoke it yourself in the web app under Settings → Tokens and issue a new one.
Peace of mind — this key is document-scoped only. A key alone cannot change your password, issue other keys, or manage login sessions. So even if it leaks, your whole account isn't taken over.
Always make sure the service URL is https://.

6 Troubleshooting

Symptom	Check / fix
`md-log` not in the list / not connected	Check that you fully restarted the client after saving settings, and that `node -v` is 22 or higher.
`npx` / `node` not found	Node.js isn't installed — install the LTS from nodejs.org and restart the terminal/app.
Every operation fails with an auth error (401)	The key is wrong, expired, or revoked. Paste the key again exactly (including `mdlog_pat_`, no spaces) or re-issue it under Settings → Tokens.
Connected but no response / timeout	Check that `MDLOG_API_BASE_URL` exactly matches the service URL (`https://app.md-log.com/api/v1`, including the trailing `/api/v1`).
Saving works but “token/session management” is refused	That's expected — this key is document-scoped and has no account-management permission.
File path error (VALIDATION)	File names must end in `.md`, and `..`, backslashes, and empty folder names are not allowed.

If none of the above helps, capture your client name and the on-screen error message and contact md-log support (support@md-log.com). (Please mask the key so it isn't visible in the capture.)

7 FAQ

Q. Do I need to install anything?

The remote (URL) method needs nothing installed — connect with only the URL and your key (recommended). The local (npx) method just needs Node.js; the connection tool is fetched and run automatically by npx on first use, so no separate install or build is needed.

Q. Can I use one key on multiple devices?

Yes. Put the same key and URL in each device's client settings. Just keep the key secret.

Q. How do I change or revoke a key?

In the web app under Settings → Tokens you can revoke the existing key and issue a new one yourself. After getting a new key, replace only the MDLOG_PAT value in your settings and restart the client.

Q. Does it work offline?

No. Documents are stored on the service server, so you need a network that can reach the MDLOG_API_BASE_URL server.