콘텐츠로 이동
Oleaflyv0.4.12

연결

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를 조작하게 하고 싶을 때 쓰는 방법입니다.

양방향 MCP한쪽 방향에서는 Claude Desktop, Cursor, Codex 같은 내 컴퓨터의 MCP 클라이언트가 베어러 토큰으로 127.0.0.1의 Oleafly MCP 서버에 연결합니다. 이 클라이언트는 프로젝트를 읽고, 편집하고, 컴파일할 수 있으며, 어떤 변경이 내 확인을 기다릴지는 승인 정책이 정합니다. 다른 방향에서는 Oleafly 내장 어시스턴트가 내가 추가한 MCP 서버의 도구를 씁니다. 명령을 실행하는 로컬 서버일 수도 있고 URL에 있는 원격 서버일 수도 있습니다.내 MCP 클라이언트가 Oleafly의 도구를 사용Oleafly 어시스턴트가 다른 MCP 서버를 사용MCP 클라이언트Claude Desktop,Cursor, CodexOleafly MCP127.0.0.1만프로젝트읽기, 편집, 컴파일베어러 토큰승인어시스턴트Oleafly에 내장로컬 서버명령 실행원격 서버URL에 연결양방향 MCP한쪽 방향에서는 Claude Desktop, Cursor, Codex 같은 내 컴퓨터의 MCP 클라이언트가 베어러 토큰으로 127.0.0.1의 Oleafly MCP 서버에 연결합니다. 이 클라이언트는 프로젝트를 읽고, 편집하고, 컴파일할 수 있으며, 어떤 변경이 내 확인을 기다릴지는 승인 정책이 정합니다. 다른 방향에서는 Oleafly 내장 어시스턴트가 내가 추가한 MCP 서버의 도구를 씁니다. 명령을 실행하는 로컬 서버일 수도 있고 URL에 있는 원격 서버일 수도 있습니다.내 MCP 클라이언트가 Oleafly를 사용Oleafly 어시스턴트가 서버를 사용MCP 클라이언트Claude Desktop, CursorOleafly MCP127.0.0.1만프로젝트읽기, 편집, 컴파일베어러 토큰승인어시스턴트Oleafly에 내장로컬 서버명령 실행원격 서버URL에 연결
내 컴퓨터의 MCP 클라이언트는 127.0.0.1과 토큰을 통해 Oleafly의 프로젝트 도구에 접근합니다. 다른 방향에서는 Oleafly 어시스턴트가 내가 추가한 MCP 서버의 도구를 쓸 수 있습니다.
  1. 설정 → 연동 → Oleafly MCP를 엽니다.
  2. MCP 서버 사용을 켭니다.

서버는 Oleafly 프로세스가 열려 있는 동안에만 실행됩니다. 127.0.0.1에서만 수신하며 로컬 네트워크에서는 수신하지 않습니다. 프로젝트 창을 닫아도 서버는 멈추지 않습니다. MCP를 끄거나 Oleafly를 종료하면 멈춥니다.

Oleafly는 포트 5323(http://127.0.0.1:5323/mcp)을 선호합니다. 사용할 수 없으면 서버가 비어 있는 다른 로컬 포트를 자동으로 연결하고 다음 실행을 위해 저장합니다. 설정에 현재 URL이 표시됩니다. 다시 시작 버튼은 가능하면 현재 포트를 다시 쓰고, 아니면 비어 있는 다른 포트를 고릅니다.

설정에는 흔한 클라이언트용 복사 붙여넣기 스니펫이 있습니다. 선택된 포트가 5323과 다를 수 있으니 현재 URL을 복사한 다음, <token>을 설정의 베어러 토큰(표시 / 복사)으로 바꾸세요.

터미널 창
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"

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 확장 프로그램인 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/mcp.json(또는 사용하는 클라이언트의 MCP 설정)에 추가하세요.

{
"mcpServers": {
"oleafly": {
"url": "http://127.0.0.1:5323/mcp",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}

~/.grok/config.toml에 추가하세요.

[mcp_servers.oleafly]
url = "http://127.0.0.1:5323/mcp"
headers = { Authorization = "Bearer <token>" }

Oleafly 설정의 Codex CLI 스니펫을 사용하세요. 실행 중인 서버로 이어지는 stdio 브리지를 제공합니다. 항목을 Codex 설정에 추가하고 Oleafly가 표시하는 현재 URL과 토큰을 사용하세요.

~/.codex/config.toml
[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_statusOleafly 버전, 열려 있는 프로젝트, 문서 엔진, 주 문서, 마지막 컴파일 상태, 그리고 마지막 컴파일이 실패했거나 실행되지 못한 이유
list_projectsID, 이름, 엔진, 종류, 주 문서, 타임스탬프, 색상, 미리보기 상태, 내보내기 기록이 있는 프로젝트
open_projectID로 프로젝트를 열어 다른 도구가 그 프로젝트를 대상으로 하게 함
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에 연결하세요.
설정 → AI 어시스턴트 → MCP. 서버를 추가하거나, 레지스트리를 둘러보거나, 다른 도구에서 구성을 가져옵니다.
설정 → AI 어시스턴트 → MCP. 서버를 추가하거나, 레지스트리를 둘러보거나, 다른 도구에서 구성을 가져옵니다. 전체 스크린샷 열기

내장 어시스턴트에 도구를 더 주려면 설정 → AI 어시스턴트 → MCP를 여세요.

  • 레지스트리 둘러보기로 서버를 찾고 설정 방법을 확인합니다.
  • 다른 도구에서 가져오기로 기존 서버 구성을 선택합니다. 가져오기 전에 선택한 항목을 검토하세요.
  • 서버 추가로 서버를 직접 입력한 다음 연결을 확인합니다.

연결된 서버는 도구를 어시스턴트에 노출합니다. 같은 페이지에서 연결 상태를 확인하고 서버를 켜거나 끌 수 있습니다. 자격 증명과 명령은 각 서버 구성에 속하므로, 새 서버를 연결하기 전에 검토하세요.

alphaXiv도 MCP 서버로 연결되지만, 여기가 아니라 설정 → 연동 → alphaXiv에서 API 키로 설정합니다. 연결되면 이 목록에 alphaXiv로 나타납니다. 절차는 연구 자료 서비스 연결에서 다룹니다.

서버 추가 → 양식. 로컬 명령 또는 원격 URL을 고르고, 연결 필드를 채운 다음, 추가하고 확인을 사용합니다.
서버 추가 → 양식. 로컬 명령 또는 원격 URL을 고르고, 연결 필드를 채운 다음, 추가하고 확인을 사용합니다. 전체 스크린샷 열기

설정 → 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과 토큰을 서비스의 연결 정보로 바꾸세요. 연결 확인으로 연결을 확인한 다음 서버가 노출하는 도구를 검토합니다. 서버의 행에서 켜거나 끌 수 있습니다. 편집 동작으로 구성을 바꾸고, 제거 동작으로 연결을 끊습니다.

다른 도구에서 가져오기를 선택하고, 발견된 구성을 살펴본 다음, 원하는 서버를 선택하세요. 가져오기 전에 실행 파일 경로, 환경 변수, URL, 자격 증명을 검토하세요. 가져오는 것은 연결 설정이며, 서버 실행 파일을 대신 설치해 주지는 않습니다.

  1. Oleafly에서 작은 연습용 프로젝트를 엽니다.
  2. 앱에서 복사한 스니펫으로 외부 클라이언트를 연결합니다.
  3. 클라이언트에게 get_status를 호출하고 프로젝트 파일을 나열하라고 요청합니다.
  4. 주 문서를 읽고 제목 변경을 제안하라고 요청합니다.
  5. 쓰기를 승인하기 전에 Oleafly에서 그 동작을 검토합니다.
  6. 컴파일하고 PDF를 확인합니다.

Oleafly 안에서 연결한 외부 도구라면, 그 서버가 지원하는 간단한 읽기 전용 요청으로 시작해서 채팅에 나타나는 도구 카드를 확인하세요.

이미지 미리보기

AI 답변을 불러오지 못했습니다

다시 시도하거나 문서를 검색하세요.