Быстрый старт MCP

Сервер запускается на вашей машине и ходит в API Инвойсбокс вашим токеном. Токен не попадает ни в модель, ни к посредникам: он лежит в конфигурации клиента и используется только для запросов к API Инвойсбокс. Начните с демо-контура — там ничего не стоит денег. Учтите только, что демо-магазин общий для всех читателей документации: пробные счета видны всем, поэтому реальные реквизиты и персональные данные туда не вводите.

Версия 0.2.1 опубликована в npm. Команды ниже работают как есть. Версию в конфигурации указывайте явно: @invoicebox/mcp-server@0.2.1 — у платёжного инструментаlatest означает, что набор инструментов может измениться между двумя запусками одного диалога. Что-то ведёт себя не так — напишите в поддержку.

Правило до установки: отдельная сессия

Подключайте платёжный сервер в сессию, где нет серверов почты, задач и веб-поиска. Это не примечание, а часть процедуры: письмо постороннего человека в соседнем инструменте — потенциальная команда для ассистента, а здесь ассистент умеет выставлять счета. Подробнее — в безопасности.

Что понадобится

Node.js 20.11 или новее — это требование самого пакета (engines в манифесте): на старших версиях npx откажется его запускать.

Переменная	Где взять
`INVOICEBOX_API_TOKEN`	Личный кабинет; для проб — демо-токен из раздела авторизации
`INVOICEBOX_MERCHANT_ID`	Идентификатор магазина, там же
`INVOICEBOX_ENV`	`demo` или `production`
`INVOICEBOX_TOOLSETS`	Необязательно. По умолчанию только чтение; `write` добавляет счёт, отмену и отгрузку, `refund` — возвраты. Чтение включено всегда

По умолчанию сервер работает в режиме чтения: он покажет счета и статусы, но ничего не создаст. Право выставлять счета и делать возвраты включается явно — так случайная формулировка в диалоге не приведёт к денежной операции.

Claude Code

# Демо-доступ публичный, поэтому его не страшно передать флагами
claude mcp add invoicebox \
  --env INVOICEBOX_API_TOKEN=b37c4c689295904ed21eee5d9a48d42e \
  --env INVOICEBOX_MERCHANT_ID=ffffffff-ffff-ffff-ffff-ffffffffffff \
  --env INVOICEBOX_ENV=demo \
  -- npx -y @invoicebox/mcp-server@0.2.1

Claude Desktop

Откройте настройки, раздел «Разработчик», и добавьте сервер в claude_desktop_config.json:

{
  "mcpServers": {
    "invoicebox": {
      "command": "npx",
      "args": ["-y", "@invoicebox/mcp-server@0.2.1"],
      "env": {
        "INVOICEBOX_API_TOKEN": "b37c4c689295904ed21eee5d9a48d42e",
        "INVOICEBOX_MERCHANT_ID": "ffffffff-ffff-ffff-ffff-ffffffffffff",
        "INVOICEBOX_ENV": "demo"
      }
    }
  }
}

После сохранения перезапустите приложение — список инструментов подхватывается при старте.

Боевой токен

Флагами боевой токен передавать не стоит: оболочка разворачивает значение до запуска, и он попадает в аргументы процесса — виден любому, кто смотрит список процессов. Держите его в файле настроек клиента с правами только для владельца.

# ~/.claude/mcp.json — права 600, значение не проходит через командную строку
{
  "mcpServers": {
    "invoicebox": {
      "command": "npx",
      "args": ["-y", "@invoicebox/mcp-server@0.2.1"],
      "env": {
        "INVOICEBOX_API_TOKEN": "<боевой токен>",
        "INVOICEBOX_MERCHANT_ID": "<идентификатор магазина>",
        "INVOICEBOX_ENV": "production",
        "INVOICEBOX_TOOLSETS": "read,write"
      }
    }
  }
}

Версия в команде указана намеренно: latest у платёжного инструмента означает, что завтра он может обновиться сам и повести себя иначе. Обновляйтесь осознанно, прочитав, что изменилось.

Cursor и VS Code

Формат тот же, файл — .cursor/mcp.json в проекте либо настройки MCP в VS Code. Токен лучше держать в переменных окружения, а не в файле проекта: конфигурация обычно попадает в репозиторий.

{
  "mcpServers": {
    "invoicebox": {
      "command": "npx",
      "args": ["-y", "@invoicebox/mcp-server@0.2.1"],
      "env": {
        "INVOICEBOX_API_TOKEN": "${env:INVOICEBOX_API_TOKEN}",
        "INVOICEBOX_MERCHANT_ID": "${env:INVOICEBOX_MERCHANT_ID}",
        "INVOICEBOX_ENV": "demo"
      }
    }
  }
}

Агенты на LangChain и LangGraph, GigaChat, GigaAgent

Клиента MCP в этих сборках даёт не модель, а фреймворк: пакет langchain-mcp-adapters умеет и stdio, и HTTP, поэтому наш сервер подключается тем же способом, что выше, — командой запуска или адресом. Модель при этом любая из доступных LangChain: GigaChat через langchain-gigachat, ChatGPT, Claude. Автономный GigaAgent от Сбера и AIRI подключает серверы MCP каталогом коннекторов.

Ассистентам без MCP-клиента — YandexGPT в Yandex Cloud Foundation Models, навыкам Алисы, локальным моделям вроде Qwen или Llama на своём сервере вывода — нужен слой функций: тот же каталог инструментов отдаётся списком функций.

Проверка

Спросите ассистента: «покажи неоплаченные счета». Ответ приходит — сервер подключён.
Включите INVOICEBOX_TOOLSETS=write и попросите выставить счёт на демо-контуре. Ассистент покажет счёт целиком и дождётся подтверждения.
Убедитесь, что ссылка на оплату открывается, и переходите на боевой токен.

Если что-то не работает

Сервер не стартует. Он проверяет токен при запуске и пишет причину в поток ошибок клиента — там будет видно, дело в токене или в идентификаторе магазина.
Инструментов не видно. Клиент читает список при старте: перезапустите приложение после правки конфигурации.
Счёт не выставляется. Скорее всего, включён режим чтения — добавьте INVOICEBOX_TOOLSETS.

Что именно умеет сервер — в справочнике инструментов. Как он защищает деньги — на странице безопасности.