Persistent VPS Compute MCP

Один постоянный Debian VPS как полноценное compute environment для Notion AI и других MCP-клиентов. Модель получает не набор из десятков искусственных DevOps-инструментов, а один нормальный root-терминал — почти как работа по SSH.

Чем это отличается от обычного «MCP для команд»

MCP поддерживает обычные и интерактивные терминальные процессы:

• run — запустить bash -lc <command>;

• open — открыть интерактивный root-shell;

• read / write — читать вывод и отправлять ввод;

• interrupt — Ctrl+C;

• close — закрыть только терминальный процесс;

• list — найти сохранённые терминальные процессы.

Файлы, установленные пакеты, репозитории, базы данных, Docker volumes и deployed-сервисы сохраняются между MCP-вызовами и чатами.

Related MCP server: TermPipe MCP

Архитектура

flowchart LR
    A[Notion Agent] -->|HTTPS + Bearer token| B[Caddy :443]
    B -->|loopback only| C[MCP :8766]
    C --> D[one terminal tool]
    D -->|root PTY| E[permanent Debian VPS]
    E --> F[systemd services]
    E --> G[Docker Compose]
    E --> H[projects and databases]

Внутренний Python-порт слушает только 127.0.0.1. В интернет выходят только Caddy и стандартные порты 80/443.

Требования

• чистый или контролируемый VPS с Debian 12+ либо Ubuntu 22.04+;

• вход под root или пользователь с sudo;

• минимум 1 vCPU и 1 GB RAM;

• домен или поддомен, например mcp.example.com;

• DNS A/AAAA уже указывает на VPS;

• TCP 80 и 443 разрешены у провайдера и в firewall;

• для Custom MCP в Notion — тариф Business или Enterprise и разрешение администратора workspace (официальная справка Notion).

Автоустановщик сам поставит Python, virtualenv, Caddy и остальные системные зависимости. Docker не устанавливается заранее: агент сможет поставить его сам, когда он потребуется конкретному проекту.

Быстрая установка

Вариант 1: репозиторий уже доступен по SSH

Репозиторий приватный, поэтому GitHub-аккаунту или deploy key на VPS сначала нужен доступ.

git clone git@github.com:m8rneco-a11y/persistent-vps-compute-mcp.git
cd persistent-vps-compute-mcp
sudo bash install.sh

Вариант 2: без настройки Git на VPS

1. На GitHub нажмите Code → Download ZIP.

2. Распакуйте архив и загрузите папку на VPS через панель хостинга, SFTP или SCP.

3. На VPS перейдите в загруженную папку и выполните:

sudo bash install.sh

Установщик спросит только публичный домен и подтверждение. После этого он:

1. проверит ОС и входные параметры;

2. установит системные пакеты;

3. сохранит резервную копию существующей установки;

4. установит приложение в /opt/mcp-compute;

5. создаст защищённый токен в /etc/mcp-compute.env с правами 0600;

6. создаст и включит mcp-compute.service;

7. запустит полный MCP-тест через loopback;

8. добавит отдельный Caddy snippet и проверит конфигурацию до reload;

9. проверит публичный HTTPS health endpoint.

Он не меняет SSH, root-пароль, Docker, проекты и firewall. Если 80/443 закрыты у провайдера, установщик сообщит об этом, но не будет сам переписывать правила доступа.

Неинтерактивный запуск

sudo bash install.sh --domain mcp.example.com --yes

Доступные параметры:

--domain NAME     публичный DNS name
--port NUMBER     внутренний loopback-порт, по умолчанию 8766
--yes             не спрашивать подтверждение
--no-caddy        установить только приватный MCP-сервис
--rotate-token    выпустить новый токен при обновлении

Повторный запуск install.sh работает как обновление: сохраняет текущий токен, создаёт backup и переустанавливает код с зависимостями. Для принудительной смены токена добавьте --rotate-token.

Проверка после установки

sudo /opt/mcp-compute/scripts/diagnose.sh

Ожидаемое состояние:

MCP service:             active
MCP autostart:           enabled
Private listener:        127.0.0.1:8766
Local health:            ok
Caddy:                   active
Public health:           ok

Публичные адреса:

https://mcp.example.com/healthz
https://mcp.example.com/mcp

/healthz публичный и возвращает только ok. /mcp без правильного Bearer-токена возвращает 401.

Получение Bearer-токена

Выполните только на VPS:

sudo /opt/mcp-compute/scripts/show-token.sh

Команда выводит чистое значение — без MCP_TOKEN= и без Bearer . Не вставляйте токен в README, Skill, issue, скриншот или обычное сообщение.

Подключение к Notion AI

Полная пошаговая инструкция находится в docs/NOTION_SETUP.md.

1. Откройте Custom MCP

Settings → Connections → Discover → MCP → Custom MCP.

2. Введите адрес

В поле URL укажите свой адрес с обязательным /mcp и нажмите Connect.

3. Добавьте имя и токен

Укажите имя Persistent VPS Compute, выберите Bearer token и вставьте значение, полученное командой show-token.sh.

После подключения Notion увидит ровно один инструмент terminal.

• Always ask подходит для первого теста.

• Run automatically уменьшает количество подтверждений.

• Always allow даёт поведение, максимально близкое к Devin, но одновременно разрешает агенту выполнять любые root-команды без ручного подтверждения.

Установка Skill

Готовый текст находится в notion-skill/SKILL.md. В нём нет домена, аккаунтных ID, токена или других секретов, поэтому один и тот же Skill можно переносить между workspace и аккаунтами.

Откройте Library → Skills, нажмите New и вставьте содержимое файла в новую страницу.

Рекомендуемые свойства:

Name: Persistent VPS Compute
Description: Use the connected permanent VPS to develop, test, deploy, debug, and operate software end to end through one root terminal.
Use automatically: On

Для Custom Agent добавьте созданную страницу Skill в Tools & Access.

Примеры задач для агента

Разработай Telegram-бота по этому ТЗ. Сам установи нужные инструменты,
напиши код, прогони тесты и оставь production-сервис работающим после завершения.

Проверь, почему API отвечает 502. Найди причину на VPS, исправь её,
перезапусти только нужный сервис и проверь публичный endpoint.

Разверни этот репозиторий через Docker Compose, настрой автозапуск,
healthcheck и обратный прокси. Не трогай остальные проекты на сервере.

Skill объясняет агенту, что закрытие session_id завершает только конкретный shell, а не удаляет машину. Долгоживущие приложения должны работать через systemd или Docker Compose.

Обслуживание

Статус и диагностика

sudo /opt/mcp-compute/scripts/diagnose.sh
sudo systemctl status mcp-compute
sudo journalctl -u mcp-compute -f

Смена токена

sudo /opt/mcp-compute/scripts/rotate-token.sh

После ротации обновите токен во всех MCP-клиентах. Старый перестаёт работать сразу после рестарта сервиса.

Обновление

git pull
sudo bash install.sh

Установщик сохранит код и конфигурацию предыдущей версии в:

/root/mcp-compute-backups/<UTC timestamp>/

Удаление

sudo bash uninstall.sh

По умолчанию токен, MCP state и audit log сохраняются. Полное удаление только MCP-данных:

sudo bash uninstall.sh --purge

Uninstaller никогда не удаляет проекты, базы, Docker containers/volumes или сторонние systemd-сервисы.

Перенос между Notion-аккаунтами

• Skill переносится как обычная Notion-страница или через этот SKILL.md.

• Сам VPS и MCP URL не зависят от Notion-аккаунта.

• Каждый новый Notion Agent или Custom Agent создаёт собственное подключение и заново вводит Bearer-токен.

• Если старый аккаунт больше не должен иметь доступ, отключите его и ротируйте токен.

Текущая версия сервера использует один общий токен. Если нескольким людям нужен одновременный независимый доступ с точечным отзывом, добавьте multi-token authentication перед выдачей доступа.

Что проверяет CI

GitHub Actions при каждом push и pull request:

• проверяет синтаксис всех Bash-скриптов;

• запускает ShellCheck;

• компилирует Python;

• поднимает MCP от root на временном loopback-порту;

• выполняет полный end-to-end тест.

E2E-набор проверяет health, отказ без авторизации, блокировку чужого Origin, единственный tool, настоящий uid=0, очистку дочернего environment, сохранение файлов между вызовами, async polling и интерактивный PTY.

Структура репозитория

.
├── server.py                         # MCP-сервер
├── install.sh                        # интерактивная установка/обновление
├── uninstall.sh                      # безопасное удаление MCP
├── requirements.txt                  # зафиксированные Python-зависимости
├── caddy/mcp-compute.caddy           # HTTPS reverse-proxy template
├── systemd/mcp-compute.service       # автозапуск сервера
├── scripts/
│   ├── diagnose.sh                   # безопасная диагностика
│   ├── rotate-token.sh               # ротация Bearer-токена
│   └── show-token.sh                 # вывести чистое значение токена
├── tests/test_client.py              # полный MCP smoke/E2E test
├── notion-skill/SKILL.md             # переносимый Skill для Notion
├── docs/NOTION_SETUP.md              # подробное подключение к Notion
└── docs/images/                       # отредактированные UI-скриншоты

Безопасность

Перед использованием обязательно прочитайте SECURITY.md.

Коротко:

• не публикуйте Bearer-токен;

• не открывайте внутренний порт MCP в интернет;

• не расшаривайте агента с Always allow посторонним;

• храните provider snapshots и резервные копии важных данных;

• считайте prompt injection из сайтов, issues и загруженных файлов реальной угрозой;

• лучше использовать отдельный VPS, а не сервер с критичными личными данными.

Совместимость

Протестировано на Debian 12, Python 3.11, FastMCP 3.4.7, Starlette 1.6.0 и Uvicorn 0.52.4. Транспорт — MCP Streamable HTTP, авторизация — стандартный HTTP Bearer token.