# Установка actari-mcp и плагина

Как поставить MCP-сервер actari-mcp и плагин в Claude Code и других агентов.

Агент работает с журналом через MCP-сервер `actari-mcp` и скиллы, которые ставятся двумя командами. Эта страница — справка по установке и подключению во всех вариантах. Если вы начинаете с нуля, пройдите сначала [Быстрый старт](/docs/quick-start): там то же самое по шагам, с проверкой после каждого.

## Что ставится

- **MCP-сервер `actari-mcp`** — журнал на вашей машине. Агент вызывает его инструменты, а сервер отправляет записи в облако. Нужен Node.js 22.5 или новее: сервер использует встроенный `node:sqlite`, внешних зависимостей у него нет. Данные лежат в `~/.actari/journal.db`, при первом запуске сервер создаёт каталог и базу сам.
- **Скиллы** — тексты, которые учат агента порядку работы. В пакете их два: `actari` (протокол журнала: с чего начать, статусы, где искать правила) и `feature` (ведение одной фичи от намерения до записи выпуска). Подробнее — на странице [Скиллы цикла](/docs/agents/skills).

## Claude Code

Две команды ставят и сервер, и скиллы:

```bash
claude plugin marketplace add https://github.com/actari/actari-mcp
claude plugin install actari@actari
```

Скилл `feature` вызывается в Claude Code как `actari:feature`. После установки перезапустите сессию, чтобы агент увидел новые инструменты.

## Другие агенты

Для агента, который умеет подключать MCP-серверы и скиллы (например, Cursor), скилл ставится отдельной командой, а сервер добавляется в конфиг MCP:

```bash
npx skills add actari/actari-mcp
```

```json
{ "mcpServers": { "actari": { "command": "npx", "args": ["-y", "actari-mcp"] } } }
```

Отдельный скилл можно выбрать флагом: `npx skills add actari/actari-mcp --skill feature`.

## Подключение к облаку

Журнал работает и без облака, но тогда фичи и доска остаются пустыми. Чтобы подключиться, выпустите токен на странице «MCP-токены» и скажите агенту:

```text
Подключи actari: адрес https://actari.dev, токен act_…
```

Агент вызовет `connect` с токеном. Инструмент проверяет связь и сам записывает настройки рядом с базой, вручную ничего настраивать не нужно. При ошибке связи существующие настройки не меняются.

Про токены стоит знать:

- Токен **личный**: один токен покрывает все пространства, в которых вы состоите.
- Токены бывают двух видов: с правом записи и «только чтение». Для `connect` и `sync` нужен токен с правом записи, токен «только чтение» получит отказ `403 read-only token`. Для агентов, которым нужно только читать журнал облака, есть отдельный пакет `actari-reader` с токеном «только чтение».
- Токен попадает в историю чата. Если он больше не нужен, отзовите его на той же странице.

Токен можно не передавать через `connect`, а положить в конфиг MCP переменными окружения:

```json
{
  "mcpServers": {
    "actari": {
      "command": "npx",
      "args": ["-y", "actari-mcp"],
      "env": {
        "ACTARI_SYNC_URL": "https://actari.dev",
        "ACTARI_SYNC_TOKEN": "act_…"
      }
    }
  }
}
```

Для облака на своём сервере укажите его адрес: `connect { url: "https://actari.example.com", token: "act_…" }` или переменную `ACTARI_CLOUD_URL`. Подробности — на странице [Self-host](/docs/self-host).

## Несколько пространств

Если вы состоите в нескольких пространствах, журнал нужно разложить по ним. Вызов `sync_scope {}` показывает, что и куда уедет, а `sync_scope { workspace: "acme", projects: ["acme-web"] }` привязывает проекты к пространству по его slug. Пока проекты не привязаны, а пространств несколько, ничего не отправляется: приватность важнее удобства. С одним пространством привязка не нужна.

Чтобы отправлять один журнал в несколько облаков (например, рабочее и своё), добавьте вторую цель: `connect { alias: "lab", token: "act_…" }`. Недоступная цель не мешает остальным.

## Как понять, что агент на связи

В подвале боковой панели облака есть строка статуса агентов:

- «Подключить агента» — ни один журнал ещё не отправлял записи в это пространство;
- «Агенты на связи» — недавно был синк, рядом видно число журналов и время последнего;
- «Агенты давно не выходили» — связь была, но давно.

Во вкладке «Агенты» настроек пространства перечислены подключённые журналы: автор, проекты и время последнего синка, а ниже — политики пространства, см. [Политика проекта](/docs/agents/policy).

## Обновление

`npx -y actari-mcp` берёт актуальную версию пакета. После обновления перезапустите сессии агента: старые копии сервера не знают новых возможностей. Плагин Claude Code обновляется его собственными командами.

Если новая версия меняет схему журнала, сервер обновляет её на месте: файл `journal.db` остаётся тем же, перед обновлением рядом кладётся резервная копия `journal.db.<время>.bak`. Сессии, открытые на старой версии, продолжают писать в тот же файл. Версии до этой подменяли файл базы целиком, поэтому после выхода этой версии один раз перезапустите все открытые сессии агента — дальше это не потребуется.

## Если не получилось

Журнал не принимает задачу, в облаке пусто, сервер не стартует или токен отклоняется — все эти случаи разобраны в разделе [Неполадки и FAQ](/docs/faq).