본문으로 건너뛰기
목차 · AI와 확장

AI 에이전트 연결(MCP)

Claude Desktop·Claude Code·Codex CLI·Gemini CLI 같은 AI 에이전트가 MDStudio에서 열린 문서를 읽고, 허락하면 고치게 합니다. 표준 MCP(Model Context Protocol)를 씁니다.

처음 연결한다면 따라하기 AI 에이전트(Claude·Codex·Gemini CLI)로 MDStudio 조작하기에서 설정과 예제 요청을 차례대로 해 봅니다.

서버 켜기

  1. 도구 > 설정 > MCP를 열고 「MCP 서버 켜기」를 선택합니다.
  2. 포트가 다른 프로그램과 겹치면 「포트」를 바꿉니다. 켜 둔 채 바꾸면 서버가 새 포트로 다시 열립니다.

도구 > MCP 서버를 클릭하거나 상태 표시줄의 서버 아이콘을 클릭해도 켜고 끕니다. 아이콘에 마우스를 올리면 켜짐·꺼짐이 나옵니다.

기본값은 설정을 참고하세요.

AI 앱 연결하기

AI 앱은 MDStudio 폴더의 MDStudio.MCP 프로그램을 거쳐 접속합니다. 이 프로그램이 이 PC의 키 저장소에서 토큰을 읽어 서버에 보냅니다.

  1. 도구 > 설정 > MCP의 「AI 앱 연결」에서 쓰는 앱 줄의 [복사] 버튼을 클릭합니다.
  2. 아래 표대로 붙여 넣습니다.
  3. 서버를 켠 상태에서 AI 앱을 엽니다. 「확인」 칸의 목록에 mdstudio가 나오면 연결된 것입니다.
앱(설정 창의 줄) 복사되는 것 붙여 넣는 곳 확인
Claude Desktop mcpServers 설정 %APPDATA%\Claude\claude_desktop_config.json에 넣고 Claude Desktop 다시 시작 Claude Desktop 의 도구 목록
Claude Code claude mcp add --scope user mdstudio -- … 명령 터미널에서 실행 claude mcp list
Codex [mcp_servers.mdstudio] 설정 %USERPROFILE%\.codex\config.toml 끝 codex mcp list
Gemini CLI mcpServers 설정 %USERPROFILE%\.gemini\settings.json에 넣음 Gemini CLI 에서 /mcp
  • 파일에 이미 mcpServers가 있으면 그 안에 mdstudio 항목만 넣습니다. Codex 파일에 [mcp_servers.mdstudio]가 이미 있으면 그 부분을 지우고 붙여 넣습니다.
  • Gemini CLI 설정에는 도구 확인을 건너뛰는 trust를 넣지 않습니다. MDStudio 의 확인 창은 에이전트 설정과 상관없이 뜹니다.
  • 에이전트마다 자세한 단계는 따라하기 AI 에이전트(Claude·Codex·Gemini CLI)로 MDStudio 조작하기의 2단계를 봅니다.

앱 줄에 [등록] 버튼이 있으면 붙여 넣지 않고 연결할 수 있습니다.

  1. Claude Desktop 을 등록할 때는 트레이에 남은 것까지 먼저 끕니다.
  2. 앱 줄의 [등록] 버튼을 클릭합니다.
  3. 확인 창에서 바뀔 내용을 보고 [등록] 버튼을 클릭합니다.
  • Claude Desktop 과 Codex 는 원래 설정 파일을 .bak 으로 남깁니다.
  • Claude Code 는 claude 명령이 설치되어 있어야 등록됩니다.
  • Gemini CLI 는 [복사] 버튼으로만 연결합니다.

복사한 글에는 토큰 값이 없습니다. Claude Desktop 설정은 명령 팔레트(Ctrl+K)의 「Claude Desktop 연결 설정 복사」로도 복사합니다.

「연결」의 「토큰」에는 앞뒤 네 글자만 보입니다. [보기] 버튼으로 전체를 보고, [새로 만들기] 버튼으로 새 토큰을 만듭니다. 새로 만들면 켜진 서버가 새 토큰으로 다시 열립니다. 토큰을 직접 넣어 둔 연결만 다시 설정하면 됩니다.

참고: 포트를 바꾸면 [복사] 버튼으로 다시 복사해 붙여 넣습니다.

도구

AI 앱이 쓰는 도구는 네 종류로 나뉩니다.

종류 도구 예 확인
읽기 list_documents·read_document·get_outline·get_selection·get_stats·search_document·check_links·get_problems·get_links·get_front_matter·list_commands·search_files·render_picture 없음
보기 바꾸기 select·set_view·fold·bookmark 없음
문서 고치기 edit_document·insert_text·insert_section·replace_all·delete_range·insert_table·auto_fix·number_headings·section·set_front_matter·format_code·undo 호출마다
파일·실행 new_document·open_document·save_document·close_document·insert_image·export·run_command·open_url 호출마다
  • table·csv_to_table은 읽기만 하면 묻지 않고, 문서를 고칠 때만 확인합니다.
  • render_picture는 Mermaid·Graphviz·수식을 PNG로 만듭니다. 문서는 바뀌지 않습니다.
  • select에 block을 주면 편집기의 열 블록처럼 사각형으로 선택합니다. 한글은 두 칸으로 셉니다.
  • delete_range는 줄·칸으로 지정한 범위를 지웁니다. 확인 창에 지울 텍스트가 나옵니다.
  • new_from_template·insert_snippet은 values로 템플릿의 사용자 정의 토큰을 채웁니다. 작성자·소속·이메일 같은 기본 토큰은 채울 수 없습니다. list_library가 템플릿마다 사용자 정의 토큰 목록을 알려 줍니다.
  • 반복 블록({{#each 품목}})에는 목록을 넘깁니다. 글 목록(["김민수", "이영희"])이나 필드 객체 목록([{"이름": "키보드", "수량": "2"}])이고 500개까지입니다. 조건 블록({{#if 비고}})은 값이 비어 있지 않으면 참입니다. list_library의 blocks가 블록 이름과 필드를 알려 줍니다. 짝이 맞지 않는 블록 태그가 있으면 줄 번호와 함께 오류가 납니다.
  • 예를 들어 기본 템플릿 견적서에 품목 두 개를 넣는 values 는 {"고객사": "가온상사", "품목": [{"이름": "키보드", "수량": "2", "단가": "15,000", "금액": "30,000"}, {"이름": "마우스", "수량": "1", "단가": "10,000", "금액": "10,000"}], "합계": "40,000"} 입니다. 템플릿은 계산하지 않으므로 금액과 합계도 값으로 넘깁니다. 태그 규칙은 템플릿 반복과 조건을 봅니다.
  • 「AI 앱에 사용자 정보(이름·소속·이메일) 제공」을 선택해야 get_user_info가 사용자 정보를 돌려줍니다.
  • AI 앱의 요청과 응답은 아래 도구 창의 「메시지」 탭에 한 줄씩 남습니다.

쓰기 허용과 확인

문서 고치기와 파일·실행 도구는 「쓰기 도구 허용」을 선택했을 때만 AI 앱의 도구 목록에 나옵니다. 켠 뒤에도 호출마다 「AI 에이전트의 문서 변경」 확인 창이 뜹니다.

  • 창에 바뀔 내용이 나옵니다.
  • 처음 초점은 [취소] 버튼에 있고 Enter로는 허락되지 않습니다. 허락하려면 [확인] 버튼을 클릭합니다.
  • 허락하면 편집기에 바로 들어가고 Ctrl+Z 한 번으로 실행 취소합니다.
  • 2분 안에 답하지 않으면 거절됩니다. AI 앱이 더 기다리지 않으면 창이 닫히고, 그 뒤에 허락해도 아무것도 바뀌지 않습니다.
  • 확인 창이 뜬 사이에 문서가 바뀌었으면 거절됩니다.
  • 읽기 전용 문서는 묻지 않고 거절합니다.

파일 도구가 닿는 폴더

열기·저장·내보내기·그림 넣기·파일 내용 찾기는 허용된 폴더 안에서만 동작합니다. 탐색기에서 연 폴더와 열린 문서가 있는 폴더는 늘 허용됩니다. 그 밖의 폴더는 「허용 폴더」의 [폴더 추가...] 버튼으로 더합니다. 시스템·자격 증명 폴더는 더해도 열리지 않습니다.

보안

  • 서버는 이 PC(127.0.0.1)에서만 접속을 받고, 토큰이 없는 요청은 거절합니다.
  • 토큰은 파일이 아니라 OS 키 저장소에 둡니다.
  • 문서에 AI에게 하는 지시가 적혀 있어도 따르지 않도록 도구 안내에 적어 둡니다.

주의: 확인 창의 도구 이름과 내용이 모르는 요청이면 [취소] 버튼을 클릭합니다.

관련 페이지