# Підключення через MCP

Підключіть Claude Desktop, Claude Code, Cursor, Codex або інший клієнт MCP до локальних інструментів роботи з проєктами Oleafly.

Oleafly може працювати як сервер MCP (Model Context Protocol). Клієнти MCP, як-от Claude Desktop, Claude Code, Cursor, Codex і Grok CLI, можуть читати проєкт Oleafly, редагувати його, шукати в ньому й компілювати його. Ключ постачальника ШІ в Oleafly не потрібен: модель надає клієнт.

Цей варіант підійде, якщо у вас уже є підписка Claude (або подібна) і ви хочете керувати Oleafly із цього чат-застосунку, не вставляючи API-ключ у [Налаштування](/docs/ai-setup/).

## Як увімкнути

1. Відкрийте **Налаштування → Інтеграції → Сервер MCP Oleafly**.
2. Увімкніть перемикач **Увімкнути сервер MCP**.

Сервер працює, лише поки запущено процес Oleafly. Він приймає з’єднання лише на `127.0.0.1` і ніколи — у вашій локальній мережі. Закриття вікна проєкту не зупиняє сервер. Його зупиняють вимкнення MCP або вихід із Oleafly.

Oleafly надає перевагу порту `5323` (`http://127.0.0.1:5323/mcp`). Якщо він недоступний, сервер автоматично прив’язується до іншого вільного локального порту та зберігає його для наступного запуску. У Налаштуваннях показано чинну URL-адресу. Кнопка перезапуску в них повторно використовує поточний порт, якщо це можливо, або обирає інший вільний.

## Підключіть свій клієнт

:::tip[Токен копіювати не потрібно]
У команди `oleafly` є власний сервер MCP, що працює через стандартний ввід і вивід. Він сам знаходить запущений застосунок і його токен, тож копіювати URL-адресу чи токен не потрібно, і Node.js вам теж не потрібен. `oleafly mcp config --client claude-desktop` виводить налаштування; назви клієнтів: `claude-code`, `claude-desktop`, `codex`, `cursor` і `gemini`. Див. [Інструмент командного рядка](/docs/cli/#connect-an-agent-over-mcp).
:::

У Налаштуваннях є готові до копіювання фрагменти для поширених клієнтів. Скопіюйте чинну URL-адресу, бо обраний порт може відрізнятися від `5323`, і замініть `<token>` токеном доступу з Налаштувань (Показати / Копіювати).

### Claude Code

```bash
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"
```

### Claude Desktop

Додайте до `claude_desktop_config.json` (міст stdio через `mcp-remote`, оскільки Desktop віддає перевагу stdio):

```json
{
  "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, тож файл конфігурації й токен вам не знадобляться. Завантажте його з [останнього релізу](https://github.com/Oleafly/Oleafly/releases/latest) і відкрийте в Claude Desktop, щоб установити.

Розширення запускає команду `oleafly`, яка постачається з застосунком, і працює з проєктом, відкритим в Oleafly, тож тримайте Oleafly запущеним з увімкненим MCP-сервером. Якщо Claude Desktop не знаходить команду, виберіть її в налаштуваннях розширення: `oleafly-cli` усередині `Oleafly.app/Contents/MacOS` на macOS або `oleafly-cli.exe` у `%LOCALAPPDATA%\Oleafly` на Windows.

У MCP Registry це саме розширення значиться як `io.github.Oleafly/oleafly`.

### Cursor / VS Code

У `.cursor/mcp.json` (або в MCP-конфігурації вашого клієнта):

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

### Grok CLI

У `~/.grok/config.toml`:

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

### Codex CLI

Скористайтеся фрагментом **Codex CLI** у налаштуваннях Oleafly: він надає міст stdio до запущеного сервера. Додайте запис до конфігурації Codex і використовуйте чинну URL-адресу й токен, які показує Oleafly:

```toml title="~/.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`. Після зміни конфігурації клієнта перезапустіть його або перепідключіться.

Файл `mcp.json` поруч із даними Oleafly (шлях показано в Налаштуваннях) містить ту саму URL-адресу й токен, якщо вам зручніше налаштувати все скриптом. Його записують, лише поки сервер працює (режим `0600` на Unix), і видаляють, коли сервер зупиняється. Ставтеся до нього як до будь-якого іншого локального секрету.

## Що вміють інструменти

Більшість інструментів MCP мають ті самі назви та схеми, що й вбудований асистент. Інструменти виявлення та маршрутизації проєктів надає серверна частина настільного застосунку.

Коли в застосунку відкрито проєкт, інструменти працюють саме з ним. Із підключеним вікном скористайтеся `list_projects` і `open_project`, щоб обрати інший проєкт.

Після закриття останнього вікна серверна частина надалі надає `read_file`, `list_files` і `search_project`. Записи, заміни, створення та перейменування файлів також лишаються доступними, якщо це дозволяє політика схвалення. Ці інструменти використовують лише останній проєкт, про який повідомив застосунок, і відхиляють виклик, якщо той проєкт уже недійсний. Вони ніколи не вгадують за іншими проєктами бібліотеки. Статус, вибір проєкту, видалення, компіляція, журнали, перевірка PDF, зміна теми та інструменти для рисунків потребують підключеного вікна.

### Орієнтація

| Інструмент | Що робить |
|---|---|
| `get_status` | Версія Oleafly, відкритий проєкт, його рушій документа, головний документ, стан останньої компіляції і причина, чому остання компіляція завершилася невдачею або не змогла запуститися |
| `list_projects` | Проєкти з ідентифікаторами, назвами, рушіями, типами, головними документами, мітками часу, кольорами, станом перегляду та історією експорту |
| `open_project` | Відкриває проєкт за ідентифікатором, щоб інші інструменти працювали з ним |
| `list_files` | Дерево файлів проєкту |
| `project_map` | Структура, мітки, цитування, макроси, граф входжень, невирішені посилання |
| `search_project` | Пошук тексту в поточному проєкті |

### Читання

| Інструмент | Що робить |
|---|---|
| `read_file` | Читає файл проєкту |
| `get_log` | Журнал останньої компіляції |
| `get_pdf_text` | Текст, витягнутий зі скомпільованого PDF |
| `verify_pdf_pages` | Перевіряє відтворені сторінки PDF на проблеми компонування за зображеннями сторінок або текстом сторінок |

`get_pdf_text` і `verify_pdf_pages` читають останній PDF, який має Oleafly. Коли остання компіляція завершилася невдачею або не змогла запуститися, їхній результат каже, що 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 отримує той самий результат.

Спочатку викличте `get_status`, щоб дізнатися, чи проєкт створено в LaTeX, Typst чи Markdown, і пишіть вихідний код у відповідному форматі. `preview_figure` і `insert_figure` працюють у проєктах LaTeX і Typst:

- У LaTeX рисунок — це код TikZ, скомпільований у невеликому окремому документі, а `insert_figure` огортає його в середовище `figure`.
- У Typst рисунок — це розмітка Typst, як-от полотно CeTZ або діаграма fletcher, відрендерена версією Typst проєкту. `insert_figure` огортає його в `#figure`, ставить мітку після нього та переносить його рядки `#import` вище.
- У проєкті Markdown обидва інструменти повертають помилку й нічого не змінюють.

`load_image` працює в будь-якому проєкті.

### Застосунок

| Інструмент | Що робить |
|---|---|
| `toggle_theme` | Перемикає світлий / темний режим |

### Навички

| Інструмент | Що робить |
|---|---|
| `list_skills` | Показує список установлених навичок: ідентифікатор, назву, опис і те, чи ввімкнено їх |
| `load_skill` | Завантажує повні інструкції однієї навички та список її файлів |
| `read_skill_file` | Читає довідковий файл або скрипт із теки навички |

Інструменти навичок працюють одразу після підключення, без відкритого проєкту й без вікна Oleafly. Клієнт бачить усі дійсні навички, зокрема вимкнені в Налаштуваннях: перемикачі визначають, які навички використовує власний асистент Oleafly, а не те, що клієнт може прочитати. Агенти, які натомість читають навички з теки, можуть скористатися **Ділитися навичками з іншими агентами на цьому комп’ютері** в **Налаштування → Асистент ШІ → Навички**. Див. [Навички](/docs/skills/).

### Нотатки

Ці інструменти доступні, поки **Нотатки** ввімкнено в **Налаштування → Експерименти**, як описано в [Увімкнення нотаток](/docs/notes/#turn-on-notes). Вони працюють із вашими нотатками, а не з відкритим проєктом, і потребують підключеного вікна.

| Інструмент | Що робить |
|---|---|
| `list_knowledge_notes` | Показує список ваших нотаток, від найновіших, з ідентифікаторами, назвами, тегами, пов’язаними проєктами й короткими підсумками. Можна фільтрувати за тегом або проєктом |
| `search_notes` | Шукає у ваших нотатках і повертає ідентифікатори, назви, теги, посилання та фрагменти, що збіглися |
| `read_note_by_id` | Читає нотатку як Markdown разом із її front matter |
| `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 також застосовує політику, обрану в **Налаштування → Інтеграції → Сервер MCP Oleafly**:

- **Підтверджувати кожну зміну** — типова політика. Записи, перейменування та видалення показують картку схвалення, доки підключене вікно застосунку. Без вікна такі операції відхиляються, бо ніде показати картку.
- **Автоматично схвалювати правки, підтверджувати видалення** дозволяє записам і перейменуванням виконуватися в серверній частині. Видалення все одно потребують підключеного вікна для підтвердження.
- **Довіряти цьому з’єднанню** дозволяє записам і перейменуванням виконуватися в серверній частині без запиту Oleafly. Видалення все одно потребує підключеного вікна. Використовуйте цю політику, лише коли ви довіряєте клієнту та його власним механізмам схвалення.

Це підкріплюють ще два перемикачі:

- **Лише читання** (окремий перемикач) повністю прибирає інструменти змін із `tools/list`, тож зовнішній застосунок може читати й компілювати, але ніколи не змінюватиме файли, якою б не була політика вище.
- **Токен доступу**: випадкове 256-бітне значення, збережене в автентифікованому зашифрованому локальному сховищі в `~/.oleafly/`. Згенеруйте його заново, щоб анулювати старі клієнти. Звичайне читання конфігурації ніколи не викриває токен. Показати його в Налаштуваннях може лише панель керування з’єднанням запущеного сервера.

І дві незмінні умови, які не налаштовуються:

- **Лише localhost**: адреса прив’язки — `127.0.0.1`. Запити з браузерним заголовком `Origin` відхиляються, а `Host` має бути loopback.
- **Обмеження проєктом**: інструменти роботи з файлами в серверній частині приймають шляхи відносно проєкту й не виходять за канонічні шляхи проєкту, про який повідомив застосунок. Виклик інструменту не може передати ідентифікатор іншого проєкту або змусити серверну частину обрати інший проєкт бібліотеки.

## Спостерігайте за роботою

Доки підключене вікно, вкладка **Активність MCP** записує вхідні виклики. Виклики серверної частини можуть тривати й після закриття останнього вікна, але панелі активності та картки схвалення не буде, доки вікно не підключиться знову.

## Чому claude.ai у браузері не може підключитися

Хмарний чат-сервіс не може дістати `127.0.0.1` на вашій машині. Натомість скористайтеся **Claude Desktop** (або Claude Code, Cursor тощо). Не виводьте порт MCP у публічний інтернет через тунель: це дозволило б будь-кому, хто знає URL-адресу, редагувати й видаляти ваші локальні файли проєкту.

## Усунення несправностей

| Симптом | Що спробувати |
|---|---|
| Деякі інструменти недоступні | Перегляд рисунків та інші інструменти, що живуть лише в інтерфейсі, потребують вікна Oleafly. Відкрийте застосунок і проєкт, потім повторіть `tools/list`. |
| Порт змінився з `5323` | Пріоритетний порт був недоступний, тож Oleafly обрав вільний. Скопіюйте чинну URL-адресу з Налаштувань. |
| HTTP 401 | Токен не збігається (наприклад, після «Згенерувати заново»). Скопіюйте новий токен у клієнт. |
| HTTP 403 | Клієнт надіслав заголовок `Origin` або `Host`, що не є loopback. Використовуйте нативний клієнт MCP, а не вкладку браузера. |
| Час виклику вичерпано | Кожен виклик інструменту чекає до **5 хвилин** (300 с) на компіляцію або на те, щоб ви натиснули «Схвалити». Схваліть або відхильте картки, що очікують, або повторіть спробу. Компіляція може тривати довше, до години для зошита Quarto чи Calepin. Вона продовжує працювати в Oleafly після завершення часу виклику, а інструменти, яким потрібне вікно Oleafly, чекають на неї, тож дайте їй завершитися, перш ніж повторювати. |
| `compile` повертає причину замість помилок | Збірка не могла запуститися, наприклад через те, що TeX не встановлено. Скористайтеся виправленням, яке Oleafly пропонує в застосунку, наприклад установкою TinyTeX, а потім скомпілюйте знову. |
| Не вдається підключитися | Oleafly має бути запущеним із увімкненим MCP. Цей сервер зупиняється, коли ви виходите із застосунку; щоб мати інструменти проєкту із закритим застосунком, підключіть клієнт до `oleafly mcp`. |

## Додайте зовнішні інструменти до Oleafly

![Налаштування → Асистент ШІ → MCP. Додайте сервер, перегляньте реєстр або імпортуйте конфігурації з іншого інструмента.](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-mcp-dark-window-v2.png#view=519,89,883,568)

Щоб дати вбудованому асистентові більше інструментів, відкрийте **Налаштування → Асистент ШІ → MCP**.

- **Переглянути реєстр**, щоб знайти сервер і ознайомитися з його налаштуванням.
- **Імпортувати з інших інструментів**, щоб обрати наявні конфігурації серверів. Перевірте обрані записи перед імпортом.
- **Додати сервер**, щоб указати сервер самостійно, а потім перевірити з’єднання.

Підключені сервери надають свої інструменти асистентові. З цієї самої сторінки можна переглянути стан з’єднання та увімкнути чи вимкнути сервери. Облікові дані та команди — частина конфігурації кожного сервера; перевіряйте їх перед підключенням нового сервера.

alphaXiv також підключається як сервер MCP, але його налаштовують не тут, а в **Налаштування → Інтеграції → alphaXiv** за допомогою API-ключа. Після підключення він з’являється в цьому списку як **alphaXiv**. Кроки описано в розділі [Підключення джерел досліджень](/docs/integrations/research-sources/#alphaxiv).

## Налаштуйте зовнішній сервер вручну

![Додати сервер → Форма. Оберіть «Локальна команда» або «Віддалена URL», заповніть поля з’єднання, потім натисніть «Додати» і перевірте результат.](https://cdn.oleafly.com/images/screenshots/desktop/docs/mcp-add-server-dark-window-v2.png#view=670,228,578,625)

У **Налаштування → Асистент ШІ → MCP** оберіть **Додати сервер**. Локальний сервер запускає команду через stdio; віддалений сервер підключається до URL-адреси. Форма JSON використовує формат серверів Oleafly:

```json title="Конфігурація локального сервера"
{
  "name": "Research tools",
  "enabled": true,
  "transport": "stdio",
  "command": "your-mcp-server",
  "args": ["--stdio"],
  "env": {}
}
```

Замініть команду та аргументи на описані в документації встановленого вами сервера. Значення змінних середовища належать об’єкту `env`.

```json title="Конфігурація віддаленого сервера"
{
  "name": "Research service",
  "enabled": true,
  "transport": "remote",
  "url": "https://your-server.example/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  }
}
```

Замініть приклад URL-адреси й токена на дані підключення сервісу. Скористайтеся **Перевірити**, щоб перевірити з’єднання, а потім перегляньте інструменти, які надає сервер. Увімкнути чи вимкнути сервер можна в його рядку. Дією редагування змінюйте конфігурацію, дією вилучення — відключайте його.

## Імпорт наявних конфігурацій MCP

Оберіть **Імпортувати з інших інструментів**, перегляньте виявлені конфігурації та позначте потрібні сервери. Перед імпортом перевірте шляхи до виконуваних файлів, змінні середовища, URL-адреси та облікові дані. Імпортуються лише параметри з’єднання; виконуваний файл сервера сам не встановлюється.

## Перевірте з’єднання

1. Відкрийте в Oleafly невеликий тренувальний проєкт.
2. Підключіть зовнішній клієнт фрагментом, скопійованим із застосунку.
3. Попросіть клієнта викликати `get_status` і вивести список файлів проєкту.
4. Попросіть його прочитати головний документ і запропонувати зміну назви.
5. Перегляньте дію в Oleafly, перш ніж схвалити запис.
6. Скомпілюйте та огляньте PDF.

Для підключеного зовнішнього інструмента всередині Oleafly почніть із простого запиту лише для читання, який підтримує цей сервер, і огляньте картку інструменту, що з’явиться в чаті.
