연결
MCP로 연결
Claude Desktop, Claude Code, Cursor, Codex 또는 다른 MCP 클라이언트를 Oleafly의 로컬 프로젝트 도구에 연결합니다.
Oleafly는 MCP(Model Context Protocol) 서버로 동작할 수 있습니다. Claude Desktop, Claude Code, Cursor, Codex, Grok CLI 같은 MCP 클라이언트가 Oleafly 프로젝트를 읽고, 편집하고, 검색하고, 컴파일할 수 있습니다. 모델은 클라이언트가 제공하므로 Oleafly에 AI 제공자 키가 필요하지 않습니다.
이미 Claude(또는 비슷한) 구독이 있고, 설정에 API 키를 붙여 넣지 않고 그 채팅 앱이 Oleafly를 조작하게 하고 싶을 때 쓰는 방법입니다.
- 설정 → 연동 → Oleafly MCP를 엽니다.
- MCP 서버 사용을 켭니다.
서버는 Oleafly 프로세스가 열려 있는 동안에만 실행됩니다. 127.0.0.1에서만 수신하며 로컬 네트워크에서는 수신하지 않습니다. 프로젝트 창을 닫아도 서버는 멈추지 않습니다. MCP를 끄거나 Oleafly를 종료하면 멈춥니다.
Oleafly는 포트 5323(http://127.0.0.1:5323/mcp)을 선호합니다. 사용할 수 없으면 서버가 비어 있는 다른 로컬 포트를 자동으로 연결하고 다음 실행을 위해 저장합니다. 설정에 현재 URL이 표시됩니다. 다시 시작 버튼은 가능하면 현재 포트를 다시 쓰고, 아니면 비어 있는 다른 포트를 고릅니다.
클라이언트 연결
섹션 제목: “클라이언트 연결”설정에는 흔한 클라이언트용 복사 붙여넣기 스니펫이 있습니다. 선택된 포트가 5323과 다를 수 있으니 현재 URL을 복사한 다음, <token>을 설정의 베어러 토큰(표시 / 복사)으로 바꾸세요.
Claude Code
섹션 제목: “Claude Code”claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"Claude Desktop
섹션 제목: “Claude Desktop”claude_desktop_config.json에 추가하세요(Desktop은 stdio를 선호하므로 mcp-remote를 거치는 stdio 브리지입니다).
{ "mcpServers": { "oleafly": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "http://127.0.0.1:5323/mcp", "--header", "Authorization: Bearer <token>", "--transport", "http-only" ] } }}Claude Desktop 확장 프로그램
섹션 제목: “Claude Desktop 확장 프로그램”각 릴리스에는 Claude Desktop 확장 프로그램인 oleafly.mcpb가 포함되어 있어 설정 파일이나 토큰이 필요하지 않습니다. 최신 릴리스 (새 탭에서 열림)에서 내려받아 Claude Desktop으로 열면 설치됩니다.
확장 프로그램은 앱과 함께 제공되는 oleafly 명령을 실행하고 Oleafly에서 열려 있는 프로젝트를 다룹니다. 따라서 MCP 서버를 켠 상태로 Oleafly를 실행해 두세요. Claude Desktop이 명령을 찾지 못하면 확장 프로그램 설정에서 직접 선택하세요. macOS에서는 Oleafly.app/Contents/MacOS 안의 oleafly-cli, Windows에서는 %LOCALAPPDATA%\Oleafly의 oleafly-cli.exe입니다.
MCP Registry에는 같은 확장 프로그램이 io.github.Oleafly/oleafly로 등록되어 있습니다.
Cursor / VS Code
섹션 제목: “Cursor / VS Code”.cursor/mcp.json(또는 사용하는 클라이언트의 MCP 설정)에 추가하세요.
{ "mcpServers": { "oleafly": { "url": "http://127.0.0.1:5323/mcp", "headers": { "Authorization": "Bearer <token>" } } }}Grok CLI
섹션 제목: “Grok CLI”~/.grok/config.toml에 추가하세요.
[mcp_servers.oleafly]url = "http://127.0.0.1:5323/mcp"headers = { Authorization = "Bearer <token>" }Codex CLI
섹션 제목: “Codex CLI”Oleafly 설정의 Codex CLI 스니펫을 사용하세요. 실행 중인 서버로 이어지는 stdio 브리지를 제공합니다. 항목을 Codex 설정에 추가하고 Oleafly가 표시하는 현재 URL과 토큰을 사용하세요.
[mcp_servers.oleafly]command = "npx"args = [ "-y", "mcp-remote@latest", "http://127.0.0.1:5323/mcp", "--header", "Authorization: Bearer <token>", "--transport", "http-only"]브리지에는 Node.js와 npx가 필요합니다. 설정을 바꾼 뒤에는 클라이언트를 다시 시작하거나 다시 연결하세요.
설정에서 확인할 수 있는 Oleafly 데이터 옆의 mcp.json 파일에는 같은 URL과 토큰이 들어 있어서, 설정을 스크립트로 처리하고 싶을 때 쓸 수 있습니다. 이 파일은 서버가 실행되는 동안에만 작성되고(Unix에서는 모드 0600) 서버가 멈추면 삭제됩니다. 다른 로컬 비밀 정보처럼 다루세요.
도구로 할 수 있는 일
섹션 제목: “도구로 할 수 있는 일”대부분의 MCP 도구는 앱 안 어시스턴트와 이름과 스키마가 같습니다. 프로젝트 탐색과 라우팅 도구는 데스크톱 백엔드가 제공합니다.
도구는 앱에 열려 있는 프로젝트가 있으면 그 프로젝트를 대상으로 합니다. 연결된 창이 있으면 list_projects와 open_project로 다른 프로젝트를 선택하세요.
마지막 창이 닫힌 뒤에도 백엔드는 read_file, list_files, search_project를 계속 쓸 수 있게 합니다. 네이티브 쓰기, 바꾸기, 만들기, 이름 바꾸기도 승인 정책이 허용하면 계속 쓸 수 있습니다. 이 도구들은 앱이 마지막으로 보고한 프로젝트만 사용하며, 그 프로젝트가 더 이상 유효하지 않으면 호출을 거부합니다. 라이브러리의 다른 프로젝트를 짐작해서 쓰는 일은 없습니다. 상태, 프로젝트 선택, 삭제, 컴파일, 로그, PDF 검사, 테마 변경, 그림 도구에는 연결된 창이 필요합니다.
현황 파악
섹션 제목: “현황 파악”| 도구 | 하는 일 |
|---|---|
get_status | Oleafly 버전, 열려 있는 프로젝트, 문서 엔진, 주 문서, 마지막 컴파일 상태, 그리고 마지막 컴파일이 실패했거나 실행되지 못한 이유 |
list_projects | ID, 이름, 엔진, 종류, 주 문서, 타임스탬프, 색상, 미리보기 상태, 내보내기 기록이 있는 프로젝트 |
open_project | ID로 프로젝트를 열어 다른 도구가 그 프로젝트를 대상으로 하게 함 |
list_files | 프로젝트 파일 트리 |
project_map | 개요, 레이블, 인용, 매크로, 입력 그래프, 해결되지 않은 참조 |
search_project | 현재 프로젝트에서 텍스트 검색 |
| 도구 | 하는 일 |
|---|---|
read_file | 프로젝트 파일 읽기 |
get_log | 마지막 컴파일 로그 |
get_pdf_text | 컴파일된 PDF에서 추출한 텍스트 |
verify_pdf_pages | 페이지 이미지나 페이지 텍스트로 렌더링된 PDF 페이지의 레이아웃 문제를 점검 |
get_pdf_text와 verify_pdf_pages는 Oleafly가 가진 마지막 PDF를 읽습니다. 마지막 컴파일이 실패했거나 실행되지 못했다면, 그 PDF가 이전 컴파일에서 나왔거나 실패한 컴파일의 일부만 담은 것이므로 결과가 PDF가 오래되었다는 것과 그 이유를 알려 줍니다. get_log도 마지막 컴파일이 실행되지 못했을 때 같은 내용을 알려 주는데, 그 로그가 이전 컴파일의 것이기 때문입니다.
| 도구 | 하는 일 |
|---|---|
write_file | 파일 쓰기 또는 덮어쓰기 |
replace_in_file | 파일 안에서 찾아 바꾸기 |
create_file | 파일이나 폴더 만들기 |
rename_file | 경로 이름 바꾸기 또는 이동 |
delete_file | 파일이나 폴더 삭제 |
set_main_doc | 컴파일 시작 문서 지정 |
컴파일과 그림
섹션 제목: “컴파일과 그림”| 도구 | 하는 일 |
|---|---|
compile | 프로젝트를 PDF로 컴파일 |
preview_figure | 그림만 따로 렌더링해 PNG 이미지로 반환 |
insert_figure | 마지막으로 미리 본 그림을 문서에 삽입 |
load_image | 그림 작업을 위해 프로젝트의 이미지를 불러오기 |
compile은 빌드가 성공했는지, 오류가 무엇인지, PDF가 있는지를 알려 주고 로그의 마지막 부분으로 끝납니다. 끝난 빌드는 경고도 보고합니다. 빌드를 실행할 수 없었거나, 끝나지 않았거나, TeX 설치나 없는 Typst 버전처럼 소스 밖의 무언가가 필요하면, 결과가 이유를 알려 주고 Oleafly가 앱에서 제안하는 해결 방법의 이름을 댑니다. 이 도구는 클라이언트에게 그 사실을 사용자에게 알리고 소스는 건드리지 말라고 요청합니다. 사용자가 멈춘 컴파일은 멈춘 것으로 표시되므로, 클라이언트가 코드의 실수로 받아들이지 않습니다. Oleafly 자체 어시스턴트도 같은 결과를 받습니다.
프로젝트가 LaTeX, Typst, Markdown 중 무엇인지 알려면 먼저 get_status를 호출한 다음, 그 형식으로 소스를 쓰세요. preview_figure와 insert_figure는 LaTeX와 Typst 프로젝트에서 동작합니다.
- LaTeX에서 그림은 작은 독립형 문서로 컴파일되는 TikZ 코드이며,
insert_figure는 이를figure환경으로 감쌉니다. - Typst에서 그림은 CeTZ 캔버스나 fletcher 다이어그램 같은 Typst 마크업이며 프로젝트의 Typst 버전으로 렌더링됩니다.
insert_figure는 이를#figure로 감싸고, 레이블을 그 뒤에 두고,#import줄을 위로 옮깁니다. - Markdown 프로젝트에서는 두 도구 모두 오류를 반환하고 아무것도 바꾸지 않습니다.
load_image는 모든 프로젝트에서 동작합니다.
| 도구 | 하는 일 |
|---|---|
toggle_theme | 밝은 모드 / 어두운 모드 전환 |
| 도구 | 하는 일 |
|---|---|
list_skills | 설치된 스킬을 ID, 이름, 설명, 켜짐 여부와 함께 나열 |
load_skill | 스킬 하나의 전체 지침과 파일 목록을 불러오기 |
read_skill_file | 스킬 폴더의 참고 자료나 스크립트 읽기 |
스킬 도구는 연결 직후, 열려 있는 프로젝트나 Oleafly 창이 없어도 동작합니다. 클라이언트는 설정에서 꺼 둔 스킬을 포함해 유효한 모든 스킬을 봅니다. 설정의 스위치는 Oleafly 자체 어시스턴트가 쓰는 스킬을 정할 뿐, 클라이언트가 읽을 수 있는 범위를 정하지 않습니다. 스킬을 폴더에서 읽는 에이전트는 설정 → AI 어시스턴트 → 스킬의 이 컴퓨터의 다른 에이전트와 스킬 공유를 사용할 수 있습니다. 스킬을 참고하세요.
이 도구들은 노트 켜기에서 설명한 대로 설정 → 실험 기능에서 노트를 켜 두는 동안 사용할 수 있습니다. 열려 있는 프로젝트가 아니라 내 노트에 작동하며, 연결된 창이 필요합니다.
| 도구 | 하는 일 |
|---|---|
list_knowledge_notes | 내 노트를 최신순으로 ID, 제목, 태그, 연결된 프로젝트, 짧은 요약과 함께 나열. 태그나 프로젝트로 필터링 |
search_notes | 내 노트를 검색해 ID, 제목, 태그, 링크, 일치하는 스니펫을 반환 |
read_note_by_id | 노트 하나를 프런트 매터와 함께 Markdown으로 읽기 |
today_note | 오늘의 데일리 노트를 읽거나, 아직 없으면 그 노트가 갖게 될 제목을 반환 |
list_note_tasks | 내 노트의 체크박스 할 일을 최신 노트 순으로 나열. 노트와 미완료 또는 완료로 필터링 |
note_backlinks | 노트 하나로 링크하는 노트를 각 링크 주변의 텍스트와 함께 나열 |
append_to_note | 노트나 오늘의 데일리 노트 끝에 Markdown 추가 |
edit_note_section | 노트에서 제목 하나 아래의 부분을 다시 쓰거나 그 끝에 추가 |
create_note | 제목, Markdown, 태그, 연결된 프로젝트가 있는 노트 만들기 |
append_to_note와 edit_note_section은 노트에 직접 쓰지 않습니다. 이 도구들의 변경은 Oleafly에서 수락하기 전까지 노트에 제안으로 표시됩니다. create_note는 Oleafly에서 내 승인을 기다리며, append_to_note도 먼저 오늘의 데일리 노트를 만들어야 할 때는 그렇습니다. 이 연결 신뢰에서는 노트를 만들 때 묻지 않습니다. 공동 작업 서버로 공유한 노트는 이 방법으로 읽을 수는 있지만 바꿀 수는 없습니다. 읽기 전용은 노트를 바꾸는 도구 세 개를 제거합니다.
승인과 안전
섹션 제목: “승인과 안전”많은 MCP 클라이언트는 도구를 호출하기 전에 묻습니다. Oleafly도 설정 → 연동 → Oleafly MCP에서 선택한 정책을 적용합니다.
- 모든 변경 확인이 기본값입니다. 앱 창이 연결되어 있는 동안 쓰기, 이름 바꾸기, 삭제는 승인 카드를 표시합니다. 창이 없으면 카드를 표시할 곳이 없으므로 그 작업은 거부됩니다.
- 편집은 자동 승인, 삭제는 확인은 쓰기와 이름 바꾸기를 백엔드에서 실행하게 합니다. 삭제는 확인을 위해 여전히 연결된 창이 필요합니다.
- 이 연결 신뢰는 백엔드의 쓰기와 이름 바꾸기를 Oleafly 확인 없이 실행하게 합니다. 삭제에는 여전히 연결된 창이 필요합니다. 클라이언트와 그 클라이언트의 자체 승인 컨트롤을 신뢰할 때만 이 정책을 쓰세요.
두 가지 스위치가 이를 뒷받침합니다.
- 읽기 전용(별도의 토글)은
tools/list에서 변경 도구를 완전히 제거하므로, 위의 정책과 상관없이 외부 앱은 읽고 컴파일할 수만 있고 파일을 절대 바꿀 수 없습니다. - 베어러 토큰:
~/.oleafly/아래의 인증된 암호화 로컬 저장소에 저장되는 256비트 무작위 값입니다. 다시 만들면 이전 클라이언트가 무효화됩니다. 일반 설정 읽기에서는 토큰이 노출되지 않습니다. 설정에서는 실행 중인 서버의 연결 컨트롤만 토큰을 보여 줄 수 있습니다.
그리고 설정할 수 없는 두 가지 불변 조건이 있습니다.
- localhost 전용: 바인드 주소는
127.0.0.1입니다. 브라우저Origin헤더가 붙은 요청은 거부되고,Host는 루프백이어야 합니다. - 프로젝트 한정: 백엔드 파일 도구는 프로젝트 상대 경로를 받고, 정규화된 경로를 앱이 보고한 프로젝트로 한정합니다. 도구 호출은 다른 프로젝트 ID를 지정하거나 백엔드가 라이브러리의 다른 프로젝트를 고르게 만들 수 없습니다.
작업 지켜보기
섹션 제목: “작업 지켜보기”창이 연결되어 있는 동안 MCP 활동 탭에 들어오는 호출이 기록됩니다. 마지막 창이 닫힌 뒤에도 백엔드 호출은 계속될 수 있지만, 창이 다시 연결되기 전까지는 활동 패널도 승인 카드도 없습니다.
브라우저의 claude.ai가 연결되지 않는 이유
섹션 제목: “브라우저의 claude.ai가 연결되지 않는 이유”클라우드 채팅 서비스는 내 컴퓨터의 127.0.0.1에 접근할 수 없습니다. 대신 Claude Desktop(또는 Claude Code, Cursor 등)을 쓰세요. MCP 포트를 공용 인터넷으로 터널링하지 마세요. URL을 아는 누구나 로컬 프로젝트 파일을 편집하고 삭제할 수 있게 됩니다.
문제 해결
섹션 제목: “문제 해결”| 증상 | 시도할 것 |
|---|---|
| 일부 도구를 쓸 수 없음 | 그림 미리보기와 UI 전용 도구에는 Oleafly 창이 필요합니다. 앱과 프로젝트를 연 다음 tools/list를 다시 시도하세요. |
포트가 5323에서 바뀜 | 선호 포트를 쓸 수 없어서 Oleafly가 비어 있는 포트를 골랐습니다. 설정에서 현재 URL을 복사하세요. |
| HTTP 401 | 토큰 불일치입니다(예: 다시 만든 뒤). 새 토큰을 클라이언트에 복사하세요. |
| HTTP 403 | 클라이언트가 Origin 헤더나 루프백이 아닌 Host를 보냈습니다. 브라우저 탭이 아니라 네이티브 MCP 클라이언트를 쓰세요. |
| 호출 시간 초과 | 각 도구 호출은 컴파일이나 여러분의 승인 클릭을 최대 5분(300초) 기다립니다. 대기 중인 카드를 승인하거나 거부하거나, 다시 시도하세요. 컴파일은 더 오래 걸릴 수 있으며, Quarto나 Calepin 노트북은 최대 한 시간까지 걸립니다. 호출이 시간 초과된 뒤에도 컴파일은 Oleafly에서 계속 실행되고, Oleafly 창이 필요한 도구는 그것을 기다리므로 다시 시도하기 전에 끝나게 두세요. |
compile이 오류 대신 이유를 반환함 | TeX가 설치되어 있지 않은 경우처럼 빌드를 실행할 수 없었습니다. TinyTeX 설치처럼 앱에서 Oleafly가 제안하는 해결 방법을 쓴 다음 다시 컴파일하세요. |
| 연결할 수 없음 | MCP를 켠 상태로 Oleafly가 실행 중이어야 합니다. 이 서버는 종료하면 멈춥니다. 앱이 닫혀 있을 때 프로젝트 도구가 필요하면 클라이언트를 대신 oleafly mcp에 연결하세요. |
Oleafly에 외부 도구 추가
섹션 제목: “Oleafly에 외부 도구 추가”
내장 어시스턴트에 도구를 더 주려면 설정 → AI 어시스턴트 → MCP를 여세요.
- 레지스트리 둘러보기로 서버를 찾고 설정 방법을 확인합니다.
- 다른 도구에서 가져오기로 기존 서버 구성을 선택합니다. 가져오기 전에 선택한 항목을 검토하세요.
- 서버 추가로 서버를 직접 입력한 다음 연결을 확인합니다.
연결된 서버는 도구를 어시스턴트에 노출합니다. 같은 페이지에서 연결 상태를 확인하고 서버를 켜거나 끌 수 있습니다. 자격 증명과 명령은 각 서버 구성에 속하므로, 새 서버를 연결하기 전에 검토하세요.
alphaXiv도 MCP 서버로 연결되지만, 여기가 아니라 설정 → 연동 → alphaXiv에서 API 키로 설정합니다. 연결되면 이 목록에 alphaXiv로 나타납니다. 절차는 연구 자료 서비스 연결에서 다룹니다.
외부 서버를 직접 구성
섹션 제목: “외부 서버를 직접 구성”
설정 → AI 어시스턴트 → MCP에서 서버 추가를 선택하세요. 로컬 서버는 stdio로 명령을 실행하고, 원격 서버는 URL에 연결합니다. JSON 양식은 Oleafly의 서버 형식을 씁니다.
{ "name": "Research tools", "enabled": true, "transport": "stdio", "command": "your-mcp-server", "args": ["--stdio"], "env": {}}명령과 인자는 설치한 서버의 문서에 나온 것으로 바꾸세요. 환경 변수 값은 env 객체에 넣습니다.
{ "name": "Research service", "enabled": true, "transport": "remote", "url": "https://your-server.example/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" }}예시 URL과 토큰을 서비스의 연결 정보로 바꾸세요. 연결 확인으로 연결을 확인한 다음 서버가 노출하는 도구를 검토합니다. 서버의 행에서 켜거나 끌 수 있습니다. 편집 동작으로 구성을 바꾸고, 제거 동작으로 연결을 끊습니다.
기존 MCP 구성 가져오기
섹션 제목: “기존 MCP 구성 가져오기”다른 도구에서 가져오기를 선택하고, 발견된 구성을 살펴본 다음, 원하는 서버를 선택하세요. 가져오기 전에 실행 파일 경로, 환경 변수, URL, 자격 증명을 검토하세요. 가져오는 것은 연결 설정이며, 서버 실행 파일을 대신 설치해 주지는 않습니다.
연결 시험
섹션 제목: “연결 시험”- Oleafly에서 작은 연습용 프로젝트를 엽니다.
- 앱에서 복사한 스니펫으로 외부 클라이언트를 연결합니다.
- 클라이언트에게
get_status를 호출하고 프로젝트 파일을 나열하라고 요청합니다. - 주 문서를 읽고 제목 변경을 제안하라고 요청합니다.
- 쓰기를 승인하기 전에 Oleafly에서 그 동작을 검토합니다.
- 컴파일하고 PDF를 확인합니다.
Oleafly 안에서 연결한 외부 도구라면, 그 서버가 지원하는 간단한 읽기 전용 요청으로 시작해서 채팅에 나타나는 도구 카드를 확인하세요.