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

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

Сервер готовится. Пакет @invoicebox/mcp-server ещё не опубликован в npm, поэтому команды ниже пока не запустятся — это описание того, каким сервер будет, и приглашение сказать нам, что он вам нужен: напишите в поддержку, и мы сообщим о публикации. Состав инструментов и правила подтверждения операций уже зафиксированы и менять их не планируем.

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

Переменная	Где взять
`INVOICEBOX_API_TOKEN`	Личный кабинет; для проб — демо-токен из раздела авторизации
`INVOICEBOX_MERCHANT_ID`	Идентификатор магазина, там же
`INVOICEBOX_ENV`	`demo` или `production`
`INVOICEBOX_TOOLSETS`	Необязательно. По умолчанию только чтение; `read,invoice` разрешает счета, `read,invoice,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@1.0.0

Claude Desktop

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

{
  "mcpServers": {
    "invoicebox": {
      "command": "npx",
      "args": ["-y", "@invoicebox/mcp-server@1.0.0"],
      "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@1.0.0"],
      "env": {
        "INVOICEBOX_API_TOKEN": "<боевой токен>",
        "INVOICEBOX_MERCHANT_ID": "<идентификатор магазина>",
        "INVOICEBOX_ENV": "production",
        "INVOICEBOX_TOOLSETS": "read,invoice"
      }
    }
  }
}

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

Cursor и VS Code

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

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

Проверка

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

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

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

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