Connect your AI agent (MCP)

The md-log MCP server is the bridge that lets an AI coding agent save its work and analysis directly into md-log as Markdown (.md) reports. Set one command (npx -y md-log-mcp) and two environment variables, and it connects from Claude Code, Claude Desktop, OpenAI Codex, Cursor, and any other MCP client. Follow the steps below.

What you need first

Connecting takes exactly two values.

Value	Details
MDLOG_API_BASE_URL	https://app.md-log.com/api/v1 — the trailing /api/v1 is required.
MDLOG_PAT	Your MCP key. It starts with mdlog_pat_. Mint it yourself in Settings → Tokens; it's shown only once at creation.

Mint the key by signing in to the web app and going to Settings → Tokens. It's free for individuals — no sales inquiry, no credit card. For the full flow from account creation, see the Quickstart.

Treat the MCP key like a password. It's revealed only once at creation, so copy it somewhere safe, and re-mint it immediately if it ever leaks.

Prerequisite: Node.js 22 or newer

npx downloads the tool automatically on first run, so there's nothing to install or build by hand. You do need Node.js 22 or newer. Check your version:

node -v

If it's below 22, or if node/npx isn't found, install the LTS release from nodejs.org and restart your terminal (or app).

Per-client setup

Pick the block for your client and replace mdlog_pat_YOUR_KEY with your real key.

Remote (URL) — recommended, no install

Prefer a hosted connection with nothing to install? Point your client at the remote endpoint and pass your key as a Bearer header — no Node.js, no npx.

Claude Code:

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

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_YOUR_KEY" }
    }
  }
}

Over the remote endpoint, embed images inline (base64) — reading a local image file by path works only with the local npx method above.

Claude Code (terminal)

Register it with one command:

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 \
  -- npx -y md-log-mcp

Then check the connection with claude mcp list, or /mcp inside a chat.

Claude Desktop

Open claude_desktop_config.json and add an entry under mcpServers:

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

The config file lives here:

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

After saving, fully quit and relaunch Claude Desktop for the change to take effect.

OpenAI Codex

Add this block to ~/.codex/config.toml (that's TOML, not JSON):

[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" }

Newer versions also support the codex mcp add command.

Cursor

Add it via Settings → MCP → Add new server, or put this JSON in ~/.cursor/mcp.json (same shape as Claude Desktop):

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

A green dot next to the server means it's connected.

Other MCP clients

The idea is the same everywhere: set the command to npx, the args to -y md-log-mcp, and pass the two environment variables (MDLOG_API_BASE_URL and MDLOG_PAT).

Verify the connection

1. After saving your config, fully restart the client (required after any config edit).
2. Confirm the md-log tools appear in the tool list. In Claude Code, use claude mcp list or /mcp to check status.
3. Try a natural-language command, e.g. "Save what you just analyzed to md-log at test/hello.md." If the report saves and a version is created, you're connected.

Auto-save via the agent rules file

Instead of saying "save this" every time, add a single rule to your project's agent rules file so the agent saves a report whenever it finishes a task.

• Claude Code: CLAUDE.md
• OpenAI Codex: AGENTS.md
• Cursor: project rules

Example rule:

When you finish a meaningful task or analysis, write a report summarizing
WHAT / WHY / IMPACT and save it via the md-log save_markdown tool at
<project>/<YYYY-MM-DD>-<topic>.md, including a commit_message.

With this in place, a .md report is created automatically after each task, folders are created on demand (like mkdir -p), images upload too, and every save becomes an immutable version. That accumulated history also doubles as onboarding material for new teammates or new agents.

What your agent can do (the 15 MCP tools)

md-log's MCP server exposes 15 tools, which break down as follows:

• Work with docs (by path): save, update, append to, read, delete, move, and rename a Markdown doc
• Version history: list past versions and read a specific past version
• Folders: create, move, rename, and delete folders (folders auto-create on save)
• List & search: list files, list folders, full-text search
• Images/assets: upload an image (e.g. a screenshot)

Path rules: a filename must end in .md, and .., backslashes, empty path segments, and control characters are not allowed (paths are NFC-normalized). Every save/update/append takes a commit_message, which shows up verbatim in the version history.

To see how a human reviews those saved reports and marks them up by hand, read Review & annotate.

Troubleshooting

Symptom	Fix
Tool not listed / "not connected"	Fully restart the client after editing config. Confirm node -v is 22 or newer.
npx/node not found	Install Node.js LTS from nodejs.org and restart your terminal/app.
Everything returns an auth error (401)	The key is wrong, expired, or revoked. Re-paste it exactly (with the mdlog_pat_ prefix, no spaces) or re-mint it in Settings → Tokens.
Connects but times out	Make sure MDLOG_API_BASE_URL is exactly https://app.md-log.com/api/v1 (with the trailing /api/v1).
"Manage tokens/sessions" is refused	Expected. The MCP key is document-scoped and can't manage login, sessions, or tokens.
Path/validation error	The filename must end in .md, with no .., backslashes, or empty path segments.
Nothing saves offline	Docs are stored on the service server, so a network path to MDLOG_API_BASE_URL is required.

Key security

Treat your MCP key (mdlog_pat_...) like a password. Don't commit it to a repo or post it in public channels — keep it somewhere safe.

md-log's MCP key is document-scoped by design. The key alone cannot change your password, mint other keys, or manage login sessions — so a leaked key does not hand over your whole account. If you suspect a leak, revoke that key in Settings → Tokens and mint a new one.

To harden login itself, turn on the optional TOTP two-factor authentication (2FA). 2FA gates web and mobile login only; it does not apply to the MCP key.

Once you're connected, save your first report with the Quickstart and learn the review flow in Review & annotate. For team on-premise deployment, contact us.