AI 에이전트(MCP) 연결하기

md-log MCP는 AI 코딩 에이전트가 작업·분석 결과를 Markdown(.md) 리포트로 md-log에 직접 저장하도록 이어주는 다리입니다. 명령 한 줄(npx -y md-log-mcp)과 두 개의 환경 변수만 설정하면 Claude Code, Claude Desktop, OpenAI Codex, Cursor를 비롯한 모든 MCP 클라이언트에서 연결됩니다. 아래 순서대로 따라 하면 됩니다.

시작하기 전에 준비할 것

연결에는 딱 두 가지 값이 필요합니다.

값	내용
MDLOG_API_BASE_URL	https://app.md-log.com/api/v1 — 끝의 /api/v1를 반드시 포함해야 합니다.
MDLOG_PAT	MCP 키. mdlog_pat_로 시작합니다. Settings → Tokens에서 직접 발급하며, 생성 시 한 번만 표시됩니다.

키는 웹 앱에 로그인한 뒤 Settings → Tokens에서 발급하세요. 개인 사용자는 무료이며 별도의 영업 문의나 신용카드가 필요 없습니다. 계정 생성부터의 전체 흐름은 빠른 시작 문서를 참고하세요.

MCP 키는 비밀번호처럼 다루세요. 생성 직후 한 번만 노출되므로 안전한 곳에 복사해 두고, 노출되면 곧바로 재발급하는 것이 안전합니다.

사전 요구 사항: Node.js 22 이상

npx는 첫 실행 때 도구를 자동으로 내려받으므로 별도로 설치하거나 빌드할 것은 없습니다. 다만 Node.js 22 이상이 필요합니다. 버전을 확인하세요.

node -v

버전이 22 미만이거나 node/npx를 찾을 수 없다면 nodejs.org에서 LTS 버전을 설치하고 터미널(또는 앱)을 다시 시작하세요.

클라이언트별 설정

아래에서 사용하는 클라이언트에 맞는 블록을 골라 mdlog_pat_YOUR_KEY 자리에 실제 키를 넣으세요.

원격 연결 (URL) — 권장 · 설치 불필요

설치 없이 URL로 붙이고 싶다면, 원격 엔드포인트를 지정하고 키를 Bearer 헤더로 전달하세요. Node.js도 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 · JSON을 쓰는 클라이언트 (type은 반드시 http):

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

원격 엔드포인트에서는 이미지를 인라인(base64)으로 넣으세요 — 로컬 파일 경로로 이미지를 읽는 기능은 위의 로컬 npx 방식에서만 동작합니다.

Claude Code (터미널)

명령 한 줄로 등록합니다.

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

등록 후 claude mcp list 또는 채팅 안에서 /mcp로 연결 상태를 확인합니다.

Claude Desktop

claude_desktop_config.json을 열어 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"
      }
    }
  }
}

설정 파일 경로는 다음과 같습니다.

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

저장한 뒤 Claude Desktop을 완전히 종료했다가 다시 실행해야 설정이 반영됩니다.

OpenAI Codex

~/.codex/config.toml(JSON이 아니라 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" }

최신 버전에서는 codex mcp add 명령도 지원합니다.

Cursor

Settings → MCP → Add new server로 추가하거나, ~/.cursor/mcp.json에 아래 JSON을 넣습니다(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"
      }
    }
  }
}

서버 옆에 초록색 점이 켜지면 연결된 것입니다.

그 밖의 MCP 클라이언트

원리는 모두 같습니다. 실행 명령을 npx, 인자를 -y md-log-mcp로 지정하고, 두 개의 환경 변수(MDLOG_API_BASE_URL, MDLOG_PAT)를 넘겨 주면 됩니다.

연결 확인하기

1. 설정을 저장한 뒤 클라이언트를 완전히 다시 시작합니다(설정 파일 편집 후에는 필수입니다).
2. 도구 목록에 md-log 도구가 나타나는지 확인합니다. Claude Code에서는 claude mcp list 또는 /mcp로 상태를 볼 수 있습니다.
3. 자연어로 시켜 봅니다. 예: "방금 분석한 내용을 테스트/hello.md로 md-log에 저장해 줘." 리포트가 저장되고 버전이 하나 생기면 정상입니다.

에이전트 규칙 파일로 자동 저장하기

매번 "이거 저장해"라고 말하는 대신, 프로젝트의 에이전트 규칙 파일에 규칙 한 줄을 넣어 두면 에이전트가 작업을 마칠 때마다 리포트를 알아서 저장합니다.

• Claude Code: CLAUDE.md
• OpenAI Codex: AGENTS.md
• Cursor: 프로젝트 규칙(project rules)

예시 규칙:

의미 있는 작업이나 분석을 마치면 무엇을(WHAT) · 왜(WHY) · 어떤 영향(IMPACT)인지
요약한 리포트를 작성하고, md-log의 save_markdown 도구로
<프로젝트명>/<YYYY-MM-DD>-<주제>.md 경로에 저장한다. commit_message를 함께 넣는다.

이렇게 하면 작업이 끝날 때마다 .md 리포트가 자동으로 생성되고, 폴더는 mkdir -p처럼 자동으로 만들어지며, 이미지도 함께 업로드되고, 저장할 때마다 불변(immutable) 버전이 하나씩 쌓입니다. 쌓인 기록은 새 팀원이나 새 에이전트의 온보딩 자료로도 쓰입니다.

에이전트가 할 수 있는 일 (MCP 도구 15개)

md-log MCP는 총 15개의 도구를 제공합니다. 크게 다음과 같습니다.

• 문서 다루기(경로 기반): Markdown 문서를 저장 · 수정 · 이어쓰기(append) · 읽기 · 삭제 · 이동 · 이름 변경
• 버전 이력: 과거 버전 목록 조회 및 특정 과거 버전 읽기
• 폴더 관리: 폴더 생성 · 이동 · 이름 변경 · 삭제 (저장 시 폴더는 자동 생성)
• 목록·검색: 파일 목록, 폴더 목록, 전체 텍스트 검색
• 이미지/자산 업로드: 스크린샷 등 이미지 첨부

경로 규칙: 파일명은 .md로 끝나야 하고, ..·역슬래시·빈 경로 구간·제어 문자는 사용할 수 없습니다(NFC 정규화). 저장·수정·이어쓰기에는 항상 commit_message가 들어가며, 이 값이 버전 이력에 그대로 표시됩니다.

저장된 리포트를 사람이 검토하고 손글씨로 주석을 다는 방법은 리포트 검토 & 주석 문서를 참고하세요.

문제 해결

증상	해결
도구가 목록에 없음 / "연결 안 됨"	설정 편집 후 클라이언트를 완전히 재시작하세요. node -v가 22 이상인지 확인합니다.
npx/node를 찾을 수 없음	nodejs.org에서 Node.js LTS를 설치하고 터미널·앱을 다시 시작하세요.
모든 요청이 인증 오류(401)	키가 틀렸거나 만료·폐기됐습니다. mdlog_pat_ 접두사까지 공백 없이 정확히 다시 붙여 넣거나 Settings → Tokens에서 재발급하세요.
연결은 되는데 타임아웃	MDLOG_API_BASE_URL이 정확히 https://app.md-log.com/api/v1(끝에 /api/v1 포함)인지 확인하세요.
"토큰/세션 관리"가 거부됨	정상 동작입니다. MCP 키는 문서 전용이라 로그인·세션·토큰 관리는 할 수 없습니다.
경로 검증 오류	파일명이 .md로 끝나야 하고, ..·역슬래시·빈 경로 구간이 없어야 합니다.
오프라인에서 저장 안 됨	문서는 서비스 서버에 저장되므로 MDLOG_API_BASE_URL로의 네트워크 연결이 필요합니다.

키 보안

MCP 키(mdlog_pat_...)는 비밀번호처럼 다루세요. 코드 저장소나 공개 채널에 올리지 말고, 안전한 곳에 보관하세요.

md-log의 MCP 키는 문서 전용(document-scoped) 으로 설계되어 있습니다. 키만으로는 비밀번호를 바꾸거나, 다른 키를 발급하거나, 로그인 세션을 관리할 수 없습니다. 따라서 키가 유출되더라도 계정 전체가 넘어가지는 않습니다. 그래도 유출이 의심되면 Settings → Tokens에서 해당 키를 폐기(revoke)하고 새 키를 발급하세요.

로그인 자체를 더 강하게 보호하려면 선택 사항인 TOTP 2단계 인증(2FA)을 켜세요. 2FA는 웹·모바일 로그인에만 적용되고 MCP 키에는 적용되지 않습니다.

연결을 마쳤다면 빠른 시작으로 첫 리포트를 저장해 보고, 리포트 검토 & 주석에서 검토 흐름을 확인하세요. 팀 단위 온프레미스 도입이 필요하면 문의하기로 연락 주세요.