MCP - integracja z Claude i Cursor

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

Co potrafi

Ponad 40 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
Plany - lista Box S/M/L/XL/XXL z limitami zasobów

Pełna roadmap z planowanymi tools (metryki, addony, ssh_command, backupy, WebSocket streaming) znajduje się w repo na GitHubie.

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

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 (v2.1 - 40 tools)

Aplikacje (7):

Tool	Co robi
saplo_list_apps	Lista Twoich aplikacji
saplo_get_app	Szczegóły aplikacji
saplo_create_app	Nowa aplikacja; stack=postgres/mysql/redis stawia bazę, linked_services spina aplikację z bazą (fullstack)
saplo_app_resize	Zmiana RAM/CPU/SSD (hotplug)
saplo_restart	Restart 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 (3):

saplo_env_get / set / unset

Zmienne env (sekrety maskowane)

Porty zewnętrzne (3) - NOWE w v2.1:

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) - NOWE w v2.1:

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) - NOWE w v2.1:

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) - NOWE w v2.1:

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

Cron (4) - NOWE w v2.1:

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 (4):

saplo_domain_add	Custom domena + instrukcje DNS
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 (3) - NOWE w v2.1:

saplo_addon_list	Wszystkie addony użytkownika (Postgres bazy)
saplo_addon_postgres_create	Provisioning Postgres - zwraca creds JEDNORAZOWO
saplo_addon_remove	Deprovisioning (admin scope, DATA LOSS)

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: Postgres jako baza, Django jako backend API
spiete z ta baza, i Next.js jako frontend wskazujacy na backend"

# Claude wykona po kolei (wszystko w jednym Boxie, spiete po localhost):
1. saplo_create_app(name="db", stack="postgres")
                               -> baza Postgres, zwraca jej id
2. saplo_create_app(name="api", stack="django",
                    linked_services=[<id bazy>])
                               -> backend z DATABASE_URL=postgres://...@127.0.0.1:5432/...
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 tylko zjeść to co już sam wpłaciłeś.

Cennik (PLN / miesiąc)

Dodatek	Aktywacja	Cena cykliczna
Add-on Postgres	0 PLN	19 PLN/mc
Add-on Redis	0 PLN	19 PLN/mc
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
Dodatkowa skrzynka pocztowa	0 PLN	5 PLN/mc
Wildcard SSL	0 PLN	15 PLN/mc
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/.

Flow rozmowy z Claude

# 1. Ty:
"Stwórz mi Postgres bazę dla appki portfolio-2026"

# 2. Claude (automatycznie):
- saplo_pricing_list           → "Postgres: 0 PLN + 19 PLN/mc"
- saplo_wallet_balance         → "balance: 5 PLN"

# 3. Claude do Ciebie:
"Aktywacja darmowa, ale miesięczna opłata to 19 PLN. Twoje saldo: 5 PLN -
nie wystarczy nawet na pierwszą opłatę. Doładuj konto:
https://panel.saplo.pl/panel/wallet/?topup=20
Po doładowaniu daj znać, kontynuujemy."

# 4. Doładowujesz w panelu BLIKiem 20 PLN, wracasz do czatu:
"OK zapłaciłem"

# 5. Claude:
- saplo_wallet_balance         → "balance: 25 PLN" (5 stare + 20 nowe)
- saplo_addon_postgres_create(app_id=72)
                               → "OK, baza db_8 utworzona, przypisana,
                                  saldo po: 6 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.7 - manifest copilot + pełne zarządzanie (aplikacje, env, porty, DNS, poczta, backupy, cron, domeny, bazy jako aplikacje). Kolejne kierunki:

Wersja	Co dodajemy
v2.1 (faza B)	deployment_history/compare, metrics_current, git_status/branches, app_update/delete, domain_list/remove/verify
v2.2 (faza C)	addony (Postgres/Redis), backupy, log_tail z filtrami, `ssh_command` dla planów L+
v2.3 (faza D)	Remote MCP (HTTP + OAuth), WebSocket streaming logów, subscriptions, publikacja w marketplace

Problemy?

Wpadnij na GitHub Issues albo napisz w wsparciu.