AI 연결 가이드

AI 앱 연결하기

1. 같은 Mac에서 로컬 MCP 서버를 지원하는 AI 앱을 사용하세요. 모델과 계정은 해당 앱에서 설정합니다. Inkquation에는 모델 API 키가 필요하지 않습니다.
2. Inkquation에서 노트를 연 다음, 설정 → AI 연결에서 연결을 허용하세요. 기본적으로 꺼져 있습니다.
3. 설정 화면의 JSON 또는 TOML 구성을 복사해 AI 앱의 기존 구성에 추가하세요. 실행 파일과 연결 경로는 Mac마다 다르므로 설정 화면에 표시된 값을 사용해야 합니다.
4. AI 앱을 다시 연결하고 Inkquation을 계속 실행해 두세요. 대상 페이지가 보이도록 스크롤하세요. AI 앱에서 편집 도구 사용 승인을 요청하면, 요청한 작업을 확인한 뒤 허용하세요.

일반적인 재시작 후에도 같은 연결 구성을 사용할 수 있습니다. 연결이 끊기면 AI 클라이언트를 다시 연결하세요. AI 연결을 껐다 켠 경우 새 구성을 복사하세요. 구성에는 액세스 키가 포함되므로 다른 사람에게 공유하지 마세요.

기본 연결에는 Python 설치나 소스 코드 다운로드가 필요하지 않습니다. Inkquation을 이동하거나 이름을 바꿨다면 연결 구성을 다시 복사하세요. 웹 기반 AI 서비스의 연결 주소 입력란에 이 웹사이트 URL을 넣어도 연결되지 않습니다.

Codex 연결하기

1. Inkquation의 설정 → AI 연결에서 연결을 허용하고 “Codex / TOML”을 선택한 다음 구성을 복사합니다.
2. 텍스트 편집기로 Codex 구성 파일을 엽니다. 기본 위치는 ~/.codex/config.toml입니다. Finder에서 이동 → 폴더로 이동을 선택해 ~/.codex/를 엽니다.
3. 복사한 [mcp_servers.inkquation] 블록을 추가하고 저장합니다. 같은 블록이 있다면 해당 설정만 갱신합니다. 다른 서버와 Codex 설정은 유지하고 같은 제목을 중복해서 추가하지 마세요.
4. Inkquation을 실행한 상태에서 Codex의 MCP 연결을 다시 시작하거나, 작업을 저장한 뒤 Codex를 다시 시작합니다. 새 채팅을 열고 아래 요청으로 연결을 확인합니다.

화면에서 등록하려면 Codex의 MCP 서버 설정에서 STDIO를 선택합니다. 명령 필드에는 복사한 구성의 command 값을, 인수 필드에는 args의 각 항목을 같은 순서로 입력합니다. 이 연결은 웹사이트 URL을 사용하지 않습니다. 화면 이름은 클라이언트 버전에 따라 다를 수 있습니다.

설정이 어렵다면 같은 Mac에서 실행 중인 Codex에 다음과 같이 요청할 수 있습니다. 연결 구성에는 액세스 키가 포함되므로 채팅에 붙여 넣지 말고 로컬 구성 파일에 입력하세요.

이 Mac에서 Inkquation과 Codex를 MCP로 연결하고 싶습니다. https://inkquation.app/ko/ai/ 의 연결 방법을 읽고 구성을 복사하고 저장하는 과정을 안내해 주세요. 기존 Codex 설정을 유지하고 inkquation 항목만 추가하거나 갱신해 주세요. 액세스 키나 연결 구성을 채팅 또는 로그에 표시하지 마세요. 연결 후에는 열린 노트 목록만 가져오고 아직 노트를 편집하지 마세요.

• OpenAI 공식: Codex MCP 구성

Claude Desktop 연결하기

1. Inkquation의 AI 연결 설정에서 “Claude Desktop / JSON”을 선택하고 구성을 복사합니다.
2. Claude Desktop에서 Settings → Developer → Edit Config를 엽니다. Mac의 기본 파일은 ~/Library/Application Support/Claude/claude_desktop_config.json입니다.
3. 기존 mcpServers 객체 안에 복사한 inkquation 항목을 추가합니다. 같은 이름의 항목이 있다면 해당 항목만 갱신하고 다른 항목은 유지합니다. 빈 파일이라면 복사한 JSON 전체를 저장할 수 있습니다.
4. Inkquation은 열어 둔 채 Claude Desktop을 완전히 종료하고 다시 실행한 다음 새 채팅에서 연결을 확인합니다.

• MCP 공식: Claude Desktop 로컬 연결 방법

로컬 LLM 사용하기

Mac에서 모델을 실행하려면 로컬 모델 실행 환경과 Inkquation의 MCP 도구를 호출하는 AI 클라이언트가 필요합니다. LM Studio는 두 역할을 모두 제공하므로 여기서는 설정 예시로 사용합니다. 아래 절차는 공식 문서를 바탕으로 작성했으며, Inkquation과 함께 사용하는 전체 흐름은 아직 Mac에서 검증하지 않았습니다.

1. LM Studio의 시스템 요구 사항을 확인하고 Mac 메모리에 맞는 모델을 다운로드하여 불러옵니다. 현재 Mac 버전은 Apple Silicon을 지원합니다. 도구 호출을 지원하는 모델을 선택하고, 페이지를 읽으려면 이미지 입력도 지원하는지 확인합니다.
2. Inkquation의 설정 → AI 연결에서 연결을 허용하고 Claude Desktop / JSON 설정을 복사합니다. LM Studio 오른쪽 사이드바에서 Program → Install → Edit mcp.json을 엽니다. 화면 이름은 버전에 따라 다를 수 있습니다.
3. 기존 mcpServers 객체 안에 복사한 inkquation 항목을 추가하고 저장합니다. 같은 이름의 항목이 있으면 해당 항목만 갱신하고 다른 설정은 유지합니다. 설정에는 접근 키가 포함되어 있으므로 공개하거나 채팅에 붙여 넣지 마세요.
4. Inkquation을 열어 둔 상태에서 LM Studio 채팅의 inkquation 도구를 활성화하고, 아래 연결 확인 요청문으로 노트 목록을 가져옵니다. 목록이 반환되면 다음 요청문으로 이미지 읽기를 확인합니다.

Inkquation은 페이지를 PNG 이미지로 반환합니다. MCP 연결에 성공해도 선택한 모델이 이미지를 읽을 수 있다는 뜻은 아닙니다. AI 클라이언트도 도구 결과의 이미지를 모델에 전달할 수 있어야 합니다. 텍스트 전용 모델은 먼저 노트 목록 가져오기까지만 확인하세요.

Inkquation에서 열려 있는 노트 목록을 가져오고, 여러 개라면 어떤 노트를 읽을지 나에게 물어보세요. 읽을 수 있는 페이지 하나를 가져와 이미지에 보이는 내용 두 가지만 설명하세요. 노트는 편집하지 마세요. 이미지가 모델에 전달되지 않거나 읽을 수 없다면 내용을 추측하지 말고 그 상태를 알려 주세요.

노트 내용을 Mac 안에서 처리하려면 추론 대상을 로컬 모델로 설정하고, 클라우드 모델로 전환하거나 내용을 외부로 전송하는 도구를 사용하지 않도록 구성합니다. 모델과 실행 환경의 최초 다운로드 및 업데이트 확인은 별도의 네트워크 활동입니다.

Ollama를 사용할 때도 모델을 실행하는 것만으로 Inkquation 연결 설정이 완료되지는 않습니다. Ollama를 추론 대상으로 사용하고 로컬 STDIO MCP 서버를 등록할 수 있는 AI 클라이언트가 필요합니다. 해당 클라이언트에 설정을 추가한 뒤 도구 호출과 이미지 전달을 각각 확인하세요.

• LM Studio 공식: MCP 서버 설정
• LM Studio 공식: 시스템 요구 사항
• LM Studio 공식: 오프라인 사용
• Ollama 공식: 도구 호출

연결을 확인하는 요청

먼저 다음 내용을 AI 채팅에 복사하세요. 열린 노트가 없다면 Inkquation에서 노트 하나를 열어 둡니다.

Inkquation MCP 도구 inkquation_list_open_notes를 사용해 현재 열린 노트의 이름과 읽을 수 있는 페이지를 알려 주세요. 이번에는 연결 확인만 하므로 페이지 이미지를 가져오거나 편집하지 마세요. 도구를 사용할 수 없다면 연결되었다고 추측하지 말고 어느 단계에서 막혔는지 알려 주세요.

도구에서 결과가 반환되면 연결을 확인할 수 있습니다. 목록이 비어 있다면 노트를 열고 다시 요청하세요. “준비됨 · 클라이언트 대기 중”은 Inkquation의 준비가 끝났다는 뜻이며 AI가 연결되었다는 뜻은 아닙니다. 클라이언트 수와 도구 실행 결과를 함께 확인하세요.

실용적인 요청 예시

연결되면 아래 요청을 시도할 수 있습니다. 여러 노트가 열려 있다면 노트 이름과 페이지를 지정하세요.

• “선택한 수식의 유도 과정을 읽고, 빠진 중간 단계나 부호 오류가 있는지 검토해 줘.”
• “이 페이지의 가정, 결론, 아직 해결되지 않은 질문을 정리해서 채팅으로 설명해 줘.”
• “이 설명을 이해하는 데 도움이 되는 개략도를 만들어 노트의 빈 공간에 추가해 줘.”

AI 앱에 작업 폴더 지정하기

작업 폴더에는 AI와 함께 다룰 코드, 참고 자료, 생성한 이미지 등을 저장할 수 있습니다. 저장 위치를 선택한 뒤 노트를 새로 만들거나 복제하거나 PDF에서 가져오면, 노트가 저장된 후 빈 작업 폴더가 자동으로 준비됩니다. 노트를 복제해도 원본의 작업 파일은 복사되지 않습니다.

1. Inkquation에서 대상 노트를 만들고 노트 목록에서 마우스 오른쪽 버튼으로 클릭하세요.
2. “작업 폴더 열기”로 위치를 확인하고 “작업 폴더 경로 복사”로 실제 폴더 경로를 복사하세요.
3. Codex 등의 AI 앱에서 해당 폴더를 작업 디렉터리로 지정하고 필요한 파일 접근을 허용하세요. 그다음 이 위치에 참고 자료용 폴더를 만들어 달라고 요청할 수 있습니다.

MCP로 경로를 확인하려면 대상 노트를 열고 inkquation_list_open_notes가 반환한 note_id로 inkquation_get_workspace를 호출하세요. 인수 예시:

{
  "note_id": "<note UUID>"
}

이 읽기 전용 도구는 폴더를 만들거나 AI 앱의 작업 디렉터리 또는 파일 접근 권한을 변경하지 않습니다. 마이그레이션 중이거나 작업 폴더에 다른 문제가 있으면 workspace_unavailable 오류가 반환될 수 있습니다. Inkquation의 처리 상태와 설정을 확인한 뒤 재시도하세요.

기존 프로젝트 폴더를 노트에 연결할 수도 있습니다. 작업 파일 내용은 Inkquation의 노트 백업에 포함되지 않으므로 Git이나 별도의 백업으로 관리하세요.

Workspaces와 Library의 차이

아래 경로는 선택한 저장 위치 안의 구조를 보여 주는 예시입니다. Library/의 노트 항목은 실제 폴더를 가리키는 심볼릭 링크입니다. 링크를 통해 파일을 편집하면 실제 파일도 변경됩니다.

같은 상위 폴더에서 이름이 충돌할 때만 Experiment--1a2b3c4d처럼 짧은 ID를 붙입니다. 대소문자나 파일 이름에 적합하지 않은 문자를 바꾸면서 생기는 충돌도 포함됩니다. 짧은 ID도 겹치면 이름을 구분할 수 있을 때까지 접미사를 늘립니다.

노트 이름을 바꾸거나 이동하면 Library/ 경로가 바뀌므로, AI의 작업 디렉터리에는 복사한 실제 폴더 경로를 사용하세요. 디스크에 폴더를 만들거나 링크 이름을 바꿔도 노트 라이브러리의 노트나 폴더가 생성되거나 이름이 변경되지는 않습니다.

연결되지 않을 때

기능과 제한 사항

Inkquation은 AI 앱이 도구를 호출할 수 있게 하는 공통 프로토콜인 MCP를 지원합니다. 연결된 AI는 열린 페이지나 올가미 선택 영역을 이미지로 읽고, PNG 이미지, 도형, 점으로 정의한 펜 획을 추가할 수 있습니다. 결과를 확인하고 조건을 충족하는 추가 작업을 취소할 수도 있습니다.

AI가 추가한 도형은 채우기 없이 윤곽선만 있는 일반 펜 획으로 변환됩니다. 이 도구는 앱에서 그리는 사각형과 타원의 채우기 설정을 제공하지 않습니다. 지우개와 올가미로 편집할 수 있지만, 도형의 치수를 설정하는 전용 기능은 없습니다. 글자와 기호를 펜 획으로 그릴 수는 있으나, 편집 가능한 텍스트나 LaTeX 객체를 추가하거나 LaTeX를 컴파일하는 기능은 지원하지 않습니다. 페이지 읽기 결과도 문자 인식된 텍스트가 아닌 이미지입니다.

AI가 페이지를 편집하는 순서

1. inkquation_list_open_notes를 호출해 정확한 note_id와 page_id를 얻으세요. available: true인 페이지를 사용합니다. 대상이 불분명하면 사용자에게 먼저 확인하세요.
2. inkquation_get_page를 호출해 페이지 이미지, revision, 논리적 크기를 읽으세요. 선택 영역을 읽으려면 사용자가 먼저 올가미로 내용을 선택한 뒤 inkquation_get_selection을 호출해야 합니다.
3. 빈 공간을 선택한 다음 추가 도구를 호출하세요. 읽은 revision을 expected_revision으로 전달하고, 새로 생성한 UUID를 operation_id로 사용합니다.
4. inkquation_get_page로 결과를 확인하세요. 필요하면 해당 추가 작업의 operation_id로 inkquation_undo를 호출합니다.

도구와 인수

연결 후 tools/list가 반환하는 입력 스키마에서 사용 가능한 도구와 인수를 확인하세요. 모든 추가 도구에는 note_id, page_id, expected_revision, operation_id가 필요합니다. 아래 표의 “공통 편집 필드”는 이 네 항목을 뜻합니다.

좌표, 펜 획, 이미지의 제한

• 좌표의 원점은 페이지 왼쪽 아래입니다. x는 오른쪽으로, y는 위쪽으로 증가합니다. 축소된 PNG의 픽셀 크기가 아니라 읽기 결과에 있는 페이지의 논리적 width와 height를 사용하세요.
• 선택 영역 PNG는 잘라낸 이미지입니다. image_bounds로 페이지에서 선택 영역의 위치를 확인하세요. 잘라낸 이미지의 왼쪽 위를 페이지 원점으로 취급하면 안 됩니다.
• shapes는 호출당 1–64개 항목을 받습니다. kind는 line, rectangle, ellipse, circle, arrow 중 하나입니다. 직사각형, 타원, 원의 start와 end는 도형을 둘러싼 사각형의 대각선 양 끝 꼭짓점입니다. 원은 사각형의 너비와 높이가 같아야 합니다. 화살표는 start에서 end를 향합니다.
• strokes도 호출당 1–64개 항목을 받습니다. 각 항목의 points에는 1–4,096개 점을 넣을 수 있으며, 한 번의 호출 전체에서는 최대 16,384개 점을 사용할 수 있습니다. 점은 직선으로 연결됩니다. 점이 하나면 점을 그리고, 마지막에 시작점을 반복하면 닫힌 경로가 됩니다. 곡선은 여러 점으로 나누어 지정하세요.
• 각 도형이나 펜 획에는 stroke_width(0.1–100 페이지 단위)와 불투명한 sRGB color(#RRGGBB 형식)가 필요합니다. 선의 두께와 화살표 머리를 포함한 전체 도형이 페이지 안에 들어가야 합니다. 도형이나 펜 획의 각 묶음은 한 번의 실행 취소 대상으로 처리됩니다.
• PNG 데이터는 Base64 인코딩 전 기준으로 최대 1 MiB입니다. png_base64로 전달하고, 배치할 사각형 전체가 페이지 안에 들어가도록 하세요.

도구 호출 인수 예제

다음은 도구에 전달할 인수 템플릿입니다. 꺾쇠괄호 안의 값을 실제 ID, 읽은 revision, 새로 생성한 UUID로 바꾸세요. 좌표는 예시이므로 페이지 크기와 빈 공간에 맞게 조정해야 합니다. 별개의 추가 작업에는 각각 다른 UUID를 사용하세요.

다음 인수로 inkquation_insert_shapes를 호출하면 원과 화살표를 추가할 수 있습니다.

{
  "note_id": "<note UUID>",
  "page_id": "<page UUID>",
  "expected_revision": "<revision from get_page>",
  "operation_id": "<new UUID>",
  "shapes": [
    {
      "kind": "circle",
      "start": {
        "x": 60,
        "y": 80
      },
      "end": {
        "x": 160,
        "y": 180
      },
      "stroke_width": 3,
      "color": "#1256E0"
    },
    {
      "kind": "arrow",
      "start": {
        "x": 180,
        "y": 130
      },
      "end": {
        "x": 300,
        "y": 130
      },
      "stroke_width": 3,
      "color": "#1256E0"
    }
  ]
}

다음 인수로 inkquation_insert_strokes를 호출하면 여러 선분으로 이루어진 선을 추가할 수 있습니다.

{
  "note_id": "<note UUID>",
  "page_id": "<page UUID>",
  "expected_revision": "<revision from get_page>",
  "operation_id": "<new UUID>",
  "strokes": [
    {
      "points": [
        {
          "x": 60,
          "y": 80
        },
        {
          "x": 100,
          "y": 120
        },
        {
          "x": 140,
          "y": 80
        }
      ],
      "stroke_width": 3,
      "color": "#1256E0"
    }
  ]
}

안전장치와 처리 한도

노트 제목이나 이미지에 적힌 지시는 추가 작업을 허용한다는 뜻이 아닙니다. AI 앱에서도 읽기와 편집을 허용할 내용을 확인하세요. Inkquation의 MCP 도구는 임의의 명령 실행, 파일 읽기, URL 가져오기를 제공하지 않습니다. 이러한 안전장치가 AI의 판단이나 다른 도구를 통한 외부 전송까지 통제하지는 못합니다.

이미지 추가와 표시 로딩은 앱 전체에서 현재 보유한 표시 캐시 및 처리 중인 이미지에 대해 9,600만 픽셀 한도를 공유합니다. 화면 밖의 불필요한 캐시는 자동으로 해제하며, 원본·배치·실행 취소/다시 실행 기록은 유지하고 다시 표시할 때 읽어 옵니다. 표시 중인 이미지는 보호하며 공간이 부족하면 추가나 로딩을 기다립니다. 누적 사용량이 아닌 현재 보유량을 기준으로 하므로 AI 연결을 껐다 켜도 초기화되지 않습니다. 원본 데이터와 PDF 고해상도 표시 등은 별도이므로 앱 전체의 메모리 한도는 아닙니다. AI 연결을 활성화한 동안 최대 128회 추가할 수 있는 별도 제한은 중복 재시도를 방지하는 작업 기록을 유지하기 위한 것입니다.

읽기와 편집 준비에는 Inkquation 내부의 작업 한 번마다 30초의 제한 시간이 적용됩니다. AI가 생각하는 시간은 포함하지 않습니다. 편집이나 실행 취소가 적용된 뒤에는 제한 시간 초과, 연결 비활성화, 요청 취소로 저장이 취소되지 않도록 보호합니다. 실제 저장 실패는 계속 보고됩니다. 연결을 비활성화하면 클라이언트가 응답을 받을 수 없으므로 앱에서 결과를 확인하세요.

재시도와 실행 취소

응답이 끊겨 추가 작업의 성공 여부를 알 수 없다면, 같은 도구에 완전히 동일한 operation_id와 인수를 전달해 재시도하세요. 새 ID를 사용하면 중복으로 추가될 수 있습니다. 재시도는 기록된 작업 결과를 반환하며, 이후 수동으로 저장하거나 실행 취소한 상태를 다시 확인하지 않습니다.

MCP 실행 취소는 해당 AI 작업이 가장 최근의 실행 취소 대상이며 페이지가 바뀌지 않았을 때만 가능합니다. 설정에서 AI 연결을 끄거나 Inkquation을 다시 시작하면 작업 ID 기록이 유지되지 않습니다. 이전 작업은 앱의 실행 취소 기능으로 확인하세요.

연결 범위와 개인정보 보호

연결은 같은 Mac에서 실행되는 로컬 프로세스와 통신합니다. 이 웹사이트는 사용 설명을 제공하며, 노트를 제어하는 MCP 서버가 아닙니다. 연결을 허용하면 AI 앱이 Inkquation에서 열려 있는 노트의 사용 가능한 페이지를 읽을 수 있습니다. 클라우드 모델을 사용하면 읽은 이미지가 모델 제공업체에 전송될 수 있습니다.

AI 연결은 기본적으로 꺼져 있습니다. 활성화하면 비공개 액세스 키와 정품 내장 어댑터를 사용하는 클라이언트가 MCP를 통해 열린 노트와 선택 영역을 읽고 이미지를 삽입할 수 있습니다. 구성에는 액세스 키가 포함되므로 비공개로 유지하세요. 다시 시작한 뒤 구성이 유지되는지는 앱 버전에 따라 다릅니다. AI 연동 가이드의 연결 및 재설정 절차를 확인하세요.

AI가 읽는 내용을 확인하고, 더 이상 필요하지 않으면 AI 연결을 끄세요. 연결을 꺼도 이미 추가하거나 저장한 내용, 외부 서비스에 전달한 데이터는 삭제되지 않습니다.

• AI 연결과 개인정보 보호

사용 가능한 기능 확인

연결 절차는 2026년 9월 27일에 확인한 구현을, 작업 폴더와 Library 설명은 2026년 10월 1일의 구현을 기준으로 합니다. 배포된 모든 버전에서 이 기능을 지원한다는 뜻은 아닙니다. 연결된 서버의 tools/list를 확인하세요. 필요한 도구나 작업 폴더 메뉴가 없다면 지원하는 버전으로 업데이트한 뒤 AI 앱을 다시 연결하세요. 도구나 메뉴가 있더라도 이전 버전의 작업 폴더 자동 준비 방식과 Library 이름 규칙은 이 설명과 다를 수 있습니다.

• Inkquation 배포 현황
• MCP 도구 명세