# Подключение через 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. Откройте **Настройки → Интеграции → Oleafly MCP**.
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 также применяет политику, выбранную в разделе **Настройки → Интеграции → Oleafly MCP**:

- **Подтверждать каждое изменение** — политика по умолчанию. Записи, переименования и удаления показывают карточку подтверждения, пока окно приложения подключено. Без окна такие операции отклоняются: карточку негде показать.
- **Автоматически разрешать правки, подтверждать удаления** позволяет записям и переименованиям выполняться в бэкенде. Удаления по-прежнему требуют подключённого окна для подтверждения.
- **Доверять этому подключению** позволяет записям и переименованиям в бэкенде выполняться без запроса Oleafly. Удаление всё равно требует подключённого окна. Используйте эту политику, только если доверяете клиенту и его собственным средствам подтверждения.

Всё это дополняют ещё два переключателя:

- **Только для чтения** (отдельный переключатель) полностью убирает изменяющие инструменты из `tools/list`, поэтому внешнее приложение может читать и компилировать, но никогда не изменит файлы, независимо от политики выше.
- **Токен доступа**: случайное 256-битное значение, хранящееся в аутентифицированном зашифрованном локальном хранилище в `~/.oleafly/`. Создайте его заново, чтобы отключить старые клиенты. Обычное чтение конфигурации никогда не раскрывает токен. Его можно увидеть только в элементах управления подключением работающего сервера в настройках.

И ещё два инварианта, которые вы не настраиваете:

- **Только localhost**: адрес привязки — `127.0.0.1`. Запросы с браузерным заголовком `Origin` отклоняются, а `Host` должен быть петлевым.
- **Ограничение проектом**: файловые инструменты бэкенда принимают пути относительно проекта и не дают каноническим путям выйти за пределы проекта, о котором сообщило приложение. Вызов инструмента не может передать идентификатор другого проекта и не заставит бэкенд выбрать другой проект библиотеки.

## Наблюдение за работой

Пока окно подключено, вкладка **Активность 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`. Используйте обычный клиент 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 внешнего инструмента начните с простого запроса только на чтение, который поддерживает этот сервер, и посмотрите получившуюся карточку инструмента в чате.
