MCP - integracja z Claude i Cursor

Saplo MCP server pozwala agentowi AI (Claude Code, Claude Desktop, Codex CLI) sterować Twoim hostingiem przez Model Context Protocol. Powiedz w czacie "zdeploy mój projekt", "pokaż logi", "stwórz scaffold dla Next.js" - agent zrobi to za Ciebie, korzystając z Twoich tokenów i uprawnień.

Co potrafi

65 narzędzi do pełnego cyklu życia aplikacji - w tym składanie aplikacji fullstack (frontend + backend + baza) jednym poleceniem:

Manifest copilot - generowanie i walidacja saplo.yaml z hint-ami
Aplikacje - listowanie, tworzenie, szczegóły, restart, rollback
Deploy - z gita lub lokalnego tarballa, status, logi (HTTP poll)
Zmienne env - odczyt, ustawianie, usuwanie (sekrety zaszyfrowane)
Domeny - dodawanie z instrukcjami DNS
WordPress - instalacja, wtyczki, motywy, użytkownicy, wersja PHP, klonowanie, eksport bazy
GitHub - podłączenie repozytorium i automatyczne wdrożenie po każdym push
Plany - lista Box S/M/L/XL/XXL z limitami zasobów

Instalacja

Wymagany Node.js 20+. Jeden pakiet @saplo/cli daje Ci dwa narzędzia: CLI (komendy saplo deploy, saplo logs) oraz MCP server dla asystentów AI.

$ npm install -g @saplo/cli

Sprawdź wersję:

$ saplo --version
$ saplo mcp serve --help

Token API (jeden, na zawsze)

MCP server używa tego samego tokenu co CLI - logujesz się raz, działa wszędzie.

$ saplo login

CLI poprosi Cię o token. Wygeneruj go w panelu:

Zaloguj się na panel.saplo.pl
Wejdź w Tokeny API (lewe menu, sekcja Dostęp)
Kliknij Nowy token, wybierz zakres deploy (lub admin) i skopiuj wartość zaczynającą się od saplo_live_

Token zapisuje się w ~/.saplo/config.json (chmod 600).

Uwaga: token zobaczysz tylko raz, zaraz po utworzeniu. Trzymaj go w bezpiecznym miejscu - nigdy nie wklejaj do wiadomości czatu ani commitów.

Konfiguracja klienta

Claude Code (CLI)

Jedna komenda - token nie jest potrzebny w argumentach, jest w configu:

$ claude mcp add saplo -- saplo mcp serve

Sprawdź czy działa:

$ claude mcp list

Codex CLI

Jedna komenda, tak samo bez tokenu w argumentach:

$ codex mcp add saplo -- saplo mcp serve

Sprawdź czy działa:

$ codex mcp list

Claude Desktop

Edytuj plik konfiguracyjny:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "saplo": {
      "command": "saplo",
      "args": ["mcp", "serve"]
    }
  }
}

Token z ~/.saplo/config.json jest automatycznie podchwytywany. Jeśli wolisz w env (np. CI/CD), nadpisuje on config:

{
  "saplo": {
    "command": "saplo",
    "args": ["mcp", "serve"],
    "env": {
      "SAPLO_API_TOKEN": "saplo_live_xxx"
    }
  }
}

Zrestartuj Claude Desktop po edycji.

Back-compat: bin `saplo-mcp`

Dla kompatybilności (np. starsze configi z uvx saplo-mcp) pakiet instaluje również drugi bin: saplo-mcp - alias dla saplo mcp serve. Możesz pisać claude mcp add saplo -- saplo-mcp i będzie działać tak samo.

Dostępne narzędzia

Aplikacje (9):

Tool	Co robi
saplo_list_apps	Lista Twoich aplikacji
saplo_get_app	Szczegóły aplikacji
saplo_create_app	Nowa aplikacja (Node, Django, Docker...); baza nie jest osobnym stackiem - dopisz Postgres/MySQL/Redis jako kontener w docker-compose.yml aplikacji
saplo_app_resize	Zmiana RAM/CPU/SSD (hotplug)
saplo_restart	Restart aplikacji (startuje też zatrzymaną)
saplo_stop	Wyłączenie aplikacji (offline do czasu startu)
saplo_start	Włączenie zatrzymanej aplikacji
saplo_rollback	Powrót do poprzedniego wdrożenia
saplo_deployment_status, saplo_logs	Status + logi wdrożenia

Manifest copilot (3):

saplo_validate_manifest	Walidacja `saplo.yaml` ze wszystkimi błędami + hint-ami
saplo_init_scaffold	Generator `saplo.yaml` dla 11 stacków
saplo_list_plans	Plany hostingowe z cenami i limitami

Środowisko i wdrożenia:

saplo_deploy	Wdrożenie aplikacji (tarball lub git)
saplo_env_get / set / unset	Zmienne env, `is_secret` zapisuje sekret (zawsze maskowany)
saplo_env_mark_secret	Oznacza istniejącą zmienną jako sekret bez podawania wartości

Porty zewnętrzne (3):

saplo_port_list	Lista portów wystawionych przez aplikację
saplo_port_add	Wystawienie portu (kind=web - HTTPS subdomena, lub kind=tcp - raw TCP/UDP)
saplo_port_remove	Cofnięcie mapowania (cleanup NPM + DNS + iptables)

DNS (4):

saplo_dns_zone_list	Strefy DNS w PowerDNS
saplo_dns_zone_add	Nowa strefa (klient ustawia ns1/ns2.saplo.pl u rejestratora)
saplo_dns_record_add	Rekord A/AAAA/MX/CNAME/TXT/NS/SRV/CAA
saplo_dns_record_remove	Usunięcie rekordu (po name + type)

Poczta - Mailcow (4):

saplo_mail_list	Skrzynki dla Twojej domeny
saplo_mail_account_create	Nowa skrzynka (local_part, domain, password, quota)
saplo_mail_account_delete	Usunięcie skrzynki
saplo_mail_alias_add	Alias / mailing lista (goto = przecinkami)

Backupy (3):

saplo_backup_list	Backupy aplikacji + status
saplo_backup_create	Snapshot (in-place, lekki)
saplo_backup_restore	Przywrócenie (admin scope, destructive)

Cron (4):

saplo_cron_list	Zadania cron aplikacji
saplo_cron_add	Nowe zadanie (schedule + command)
saplo_cron_toggle	Włącz/wyłącz bez usuwania
saplo_cron_remove	Usunięcie zadania

Domeny (5):

saplo_domain_add	Custom domena + instrukcje DNS
saplo_domain_list	Same nazwy domen aplikacji (krótka lista)
saplo_customdomain_list	Lista domen aplikacji z SSL status
saplo_customdomain_remove	Usunięcie domeny (cleanup NPM + cert)
saplo_customdomain_verify	Wymuś re-check DNS + LE

Add-ony (płatne zasoby):

saplo_addon_list	Płatne add-ony użytkownika (RAM/SSD, sloty, skrzynki, priority)
saplo_addon_buy	Zakup add-onu z portfela (RAM, SSD, slot, skrzynka, priority)
saplo_addon_assign	Przypięcie add-onu do aplikacji albo odpięcie (add-on zostaje na koncie)
saplo_addon_remove	Deprovisioning (admin scope, DATA LOSS)

Konto i portfel:

saplo_box_list	Wszystkie Boxy na koncie, także puste (id potrzebne do tworzenia aplikacji)
saplo_wallet_balance	Saldo portfela
saplo_wallet_topup_create	Link do płatności imoje, którym doładujesz portfel
saplo_pricing_list	Aktualny cennik add-onów

WordPress (10):

saplo_wp_install	Świeży WordPress z kontem administratora
saplo_wp_plugin_list / saplo_wp_plugin_install	Lista i instalacja wtyczek
saplo_wp_theme_install	Instalacja motywu
saplo_wp_user_create	Nowy użytkownik WordPressa
saplo_wp_cli	Dowolne polecenie wp-cli z listy dozwolonych (destrukcyjne wymagają potwierdzenia)
saplo_wp_clone	Kopia WordPressa do innej aplikacji WP (nadpisuje docelową)
saplo_wp_db_export	Eksport bazy do pliku .sql
saplo_php_list / saplo_php_set	Dostępne wersje PHP i zmiana wersji

GitHub (6):

saplo_git_connect	Link do instalacji aplikacji Saplo na GitHubie
saplo_git_repos	Repozytoria dostępne po instalacji
saplo_git_set_repo	Wybór repozytorium i gałęzi, auto-deploy po push
saplo_git_status	Stan połączenia z repozytorium
saplo_git_deploy_key	Klucz wdrożeniowy SSH dla repozytorium prywatnego
saplo_git_disconnect	Odłączenie repozytorium

Bazy danych to NIE add-ony. Postgres, Redis i MySQL nie stawia się jako osobny moduł w panelu - dopisujesz je za darmo jako kontener w pliku docker-compose.yml aplikacji, która ich potrzebuje, i łączysz się po localhost (zmienną DATABASE_URL / REDIS_URL ustawiasz samodzielnie przez saplo_env_set).

Resources (kontekst Claude'a)

Oprócz tools MCP udostępnia "resources" - dokumenty, które asystent może wciągnąć do kontekstu sam, bez Twojej komendy:

saplo://apps - markdownowa lista Twoich aplikacji
saplo://app/{id} - szczegóły aplikacji
saplo://plans - matryca planów Box
saplo://docs/manifest - pełny JSON Schema dla saplo.yaml

Przykładowe rozmowy

Nowy projekt od zera

# Ty piszesz w czacie:
"Postaw aplikację Django o nazwie blog-2026, plan Box L, podepnij
domenę blog.example.com, dodaj zmienną DJANGO_DEBUG=False"

# Claude wykona po kolei:
1. saplo_init_scaffold(stack="django", name="blog-2026")
2. saplo_validate_manifest()
3. saplo_create_app(name="blog-2026", stack="django", plan="box-l")
4. saplo_env_set(app_id=N, vars={"DJANGO_DEBUG": "False"})
5. saplo_domain_add(app_id=N, domain="blog.example.com")

Fullstack: Next.js + Django + Postgres (jeden Box)

# Ty piszesz w czacie:
"Postaw mi fullstack: Django z Postgresem jako backend API,
i Next.js jako frontend wskazujacy na backend"

# Claude wykona po kolei (jeden Box, backend i baza w jednym docker-compose.yml):
1. saplo_create_app(name="api", stack="docker")
                               -> backend; docker-compose.yml w repo ma dwa
                                  serwisy: "web" (Django) i "db" (Postgres)
2. saplo_env_set(app="api",
                 vars={"DATABASE_URL": "postgres://user:pass@localhost:5432/api"})
                               -> Django laczy sie z Postgresem po localhost
3. saplo_create_app(name="web", stack="nextjs")
                               -> frontend
4. saplo_env_set(app="web",
                 vars={"NEXT_PUBLIC_API_URL": "https://api.twojadomena.pl"})
                               -> frontend wola backend po publicznym URL

Tak samo złożysz React + Django czy Next.js + WordPress headless - zawsze kilka aplikacji w jednym Boxie, spiętych zmienną środowiskową albo połączeniem po localhost. Więcej: Własne aplikacje i fullstack.

Debug wadliwego deployu

# Ty:
"Aplikacja portfolio-2026 nie chce wstać po ostatnim wdrożeniu"

# Claude:
1. saplo_get_app(app_id) -> sprawdza status current_deployment
2. saplo_logs(deployment_id, tail=300) -> analizuje błąd
3. Sugeruje naprawę (np. brakująca zmienna env)
4. Jeśli zgodzisz się: saplo_env_set + saplo_deploy

Płatności - prepaid wallet

Saplo używa modelu prepaid dla add-onów i innych dodatków płatnych. Doładowujesz konto raz (BLIK/karta/przelew przez Imoje), a opłaty cykliczne zjadane są z salda. Powód: AI agent (Claude przez MCP) nie ma prawa obciążać Twojej karty bez wyraźnej autoryzacji - może wykorzystać tylko środki już wpłacone do portfela.

Cennik (PLN / miesiąc)

Dodatek	Aktywacja	Cena cykliczna
Dodatkowe 2 GB RAM	0 PLN	9 PLN/mc
Dodatkowe 25 GB SSD	0 PLN	9 PLN/mc
Custom port HTTP/HTTPS	0 PLN	9 PLN/mc
Custom port TCP/UDP	0 PLN	15 PLN/mc
Poczta (w cenie planu, konta bez limitu)	-	w cenie
Priority support 1h SLA	0 PLN	99 PLN/mc

Pełny cennik dostępny też przez tool saplo_pricing_list oraz publicznie pod GET /api/v1/pricing/.

Baza danych = darmowy kontener w Twojej aplikacji

# 1. Ty:
"Dodaj Postgresa do appki portfolio-2026"

# 2. Claude:
- dopisuje serwis "db" (Postgres) do docker-compose.yml aplikacji
                               → "OK, Postgres dziala jako kontener
                                  w Twoim Boxie. 0 PLN - bez oplaty."
- saplo_env_set(app="portfolio-2026",
                 vars={"DATABASE_URL": "postgres://user:pass@localhost:5432/portfolio"})
                               → "DATABASE_URL ustawiony, polaczenie po localhost."
- saplo_deploy(app="portfolio-2026")
                               → nowy docker-compose.yml wchodzi w zycie

Baza stoi w Twoim Boxie jako część docker-compose.yml aplikacji i nie kosztuje nic dodatkowo - liczy się tylko z puli RAM/SSD planu.

Flow rozmowy z Claude - płatny add-on (portfel)

Poczta jest w cenie planu i konta tworzy się bezpłatnie przez saplo_mail_account_create. Poniżej przykład zakupu płatnego add-onu (np. dodatkowy RAM):

# 1. Ty:
"Dorzuć 2 GB RAM do mojego Boxa"

# 2. Claude (automatycznie):
- saplo_pricing_list           → "Dodatkowe 2 GB RAM: 0 PLN + 9 PLN/mc"
- saplo_wallet_balance         → "balance: 3 PLN"

# 3. Claude do Ciebie:
"Miesięczna opłata to 9 PLN, a Twoje saldo to 3 PLN - nie wystarczy.
Doładuj konto: https://panel.saplo.pl/panel/wallet/?topup=10
Po doładowaniu daj znać, kontynuujemy."

# 4. Doładowujesz w panelu BLIKiem 10 PLN, wracasz do czatu:
"OK, opłacone"

# 5. Claude:
- saplo_wallet_balance         → "balance: 13 PLN" (3 stare + 10 nowe)
- saplo_addon_buy(item_type="addon_extra_ram")
                               → "OK, +2 GB RAM dodany,
                                  saldo po: 4 PLN, kolejna opłata 24-06-2026"

Suspended state - grace 7 dni

Gdy saldo spadnie do 0 i przyjdzie czas opłaty cyklicznej, add-on idzie w stan suspended na 7 dni. Dane bazy są zachowane, ale nie obsługuje połączeń. Doładujesz w tym czasie - revive_suspended_addons_task wskrzesza go automatycznie (status wraca do active, opłata pobierana, kolejne 30 dni). Po 7 dniach grace - deprovision z danymi (Postgres: DROP DATABASE). Klient jest powiadamiany emailem na każdym kroku.

Bezpieczeństwo

Token API nigdy nie opuszcza Twojej maszyny - MCP server działa lokalnie i komunikuje się tylko z panel.saplo.pl.
Każdy token ma zakres (read, deploy, admin) - jeśli używasz Claude'a do podglądu, daj mu token read-only.
Operacje destrukcyjne (rollback, env unset, restart) Claude potwierdza z Tobą przed wykonaniem.
Wygenerowane tokeny możesz w każdej chwili unieważnić w panelu - Tokeny API.

Roadmapa

Aktualna wersja: @saplo/cli 2.11 - manifest copilot + pełne zarządzanie (aplikacje, env, porty, DNS, poczta, backupy, cron, domeny, WordPress, GitHub, portfel). Kolejne kierunki:

Co planujemy	Opis
Metryki i historia	deployment_history/compare, metrics_current, git_status/branches
ssh_command	Wykonywanie komend SSH z poziomu MCP dla planów L+
Remote MCP	HTTP + OAuth, WebSocket streaming logów, subscriptions, publikacja w marketplace

Problemy?

Napisz w wsparciu albo załóż zgłoszenie w panelu.