--- title: "Serwery — API v1 i MCP | Dokumentacja Nodea" description: "Pełny reference modułu Serwery: endpointy REST API v1 (CRUD, statystyki, komponenty, operacje, WAF, cykl życia VM start/reboot/stop), zakresy infra:read/write/delete, narzędzia MCP, maskowanie sekretów i przykłady curl oraz JSON-RPC." url: "https://nodea.pl/pl/dokumentacja-api/servers" lang: "pl" updated: "2026-07-16" --- # Serwery — API v1 i MCP | Dokumentacja Nodea > Reference modułu Serwery — endpointy API v1 (lista, podgląd, edycja, usuwanie, test SSH, notatka, statystyki, komponenty, operacje, WAF, cykl życia VM), zakresy infra:read/write/delete, polityka własności, maskowanie sekretów, 17 narzędzi MCP i przykłady. Moduł **Serwery** to najobszerniejsza część API infrastruktury: pełny cykl życia instancji obliczeniowej — edycja, usuwanie, test połączenia SSH, notatka, statystyki wydajności, komponenty (instalacja oprogramowania), historia operacji na serwerze (wykonywanych przez agenta nodead), status WAF z regułami oraz cykl życia sparowanej maszyny wirtualnej Proxmox (start / reboot / stop). Dokument opisuje warstwę REST API v1 (/api/v1/servers) oraz 17 narzędzi MCP z tego modułu. **Od 12.10.2026 nie można dodawać serwerów spoza chmury nodea.** POST /api/v1/servers i POST /api/v1/servers/{server}/clone zwracają 410 foreign\_servers\_disabled, a narzędzia MCP server-create i server-clone zawsze kończą się błędem foreign\_servers\_disabled. Nowe instancje obliczeniowe (maszyny wirtualne w chmurze nodea) zamawia się w panelu; serwery dedykowane obsługuje osobny moduł. ## Uwierzytelnianie i zakresy (scopes) API v1 uwierzytelnia się tokenem osobistym Passport przez nagłówek Authorization: Bearer \. Poziomy dostępu: - infra:read — listowanie, podgląd, statystyki, komponenty, operacje, status WAF. - infra:write — edycja + akcje niedestrukcyjne (test SSH, notatka, instalacja komponentu, start i reboot VM, przełączanie reguły WAF). - infra:delete — usunięcie serwera (kaskadowo niszczy sparowaną VM) oraz **stop VM** (wyłączenie produkcyjnej maszyny jest destrukcyjne). Cały moduł jest dodatkowo bramkowany flagą Pennant features:servers — wyłączenie modułu ukrywa go zarówno w web UI, jak i w API/MCP. Limit zapytań: throttle:api-v1 = 240/min na użytkownika tokenu. ## Własność i widoczność (ServerPolicy) **Serwery bez maszyny wirtualnej** pozostają zasobem osobistym i działają jak dotąd. Dostęp na poziomie wiersza wymusza ServerPolicy: **view** = właściciel LUB zaakceptowany udział FOREIGN (współpracownik może korzystać ze wszystkich endpointów odczytu), **manage** = właściciel (pivot OWNER). Wszystkie mutacje wymagają manage — także w panelu WWW (instalacja komponentów, edycja, notatka, test SSH, akcje komponentów); udział FOREIGN daje wyłącznie odczyt. **Wspólna pula administratorów:** administrator Nodea z potwierdzonym 2FA (gdy wymuszanie 2FA dla adminów jest włączone) ma **manage** i **delete** na poziomie właściciela dla serwerów bez VM innych takich administratorów; administrator bez 2FA, były administrator i klient z udziałem FOREIGN — nie. Uprawnienie liczone jest na żywo z roli i 2FA, nie z samego wiersza udziału. Serwer istniejący, ale niewidoczny dla tokenu zwraca 403 (polityka); nieznany identyfikator — 404 (route model binding). Zaproszenia jeszcze niezaakceptowane nie wyciekają na listę, a zaakceptowane udziały FOREIGN są widoczne (parytet z web). ### Serwery z maszyną wirtualną — konto klienta **Serwer sparowany z maszyną wirtualną Proxmox należy do konta klienta tej VM** (patrz [Konta klientów](https://nodea.pl/pl/dokumentacja-api/accounts)). Żądanie działa w bieżącym koncie (przypięcie tokenu → nagłówek X-Account-Id → konto domyślne): - **VM bieżącego konta:** odczyt wymaga uprawnienia konta products; akcje (edycja, start/stop/reboot VM, WAF, komponenty, test SSH, notatka) — products + manageproducts; usunięcie — roli **właściciela** konta (członek, nawet z manageproducts, dostaje 403 account\_owner\_required). Brak flagi → 403 account\_permission\_denied z polem permission. - **VM innego konta bez udziału** (brak wiersza pivot) → 404, także gdy to inne konto należy do Ciebie — token działający w koncie A nigdy nie dotyka VM konta B. - **VM innego konta z udziałem monitoringu** (pivot OWNER/FOREIGN) → tylko odczyt; mutacje zwracają 403. - **Lista** (GET /servers) = serwery własne i udostępnione + serwery z VM **bieżącego konta** (gdy masz products) z etykietą ownership: "account"; serwery z VM Twoich *innych* kont są ukryte. - meta.can\_manage w szczegółach uwzględnia kontekst konta — dla VM spoza bieżącego konta zawsze false. **Kolejność sprawdzeń przy usuwaniu** (DELETE /servers/{server}): widoczność (403/404) → 423 managed\_by\_whmcs (VM zarządzana przez moduł WHMCS ModulesGarden — zawsze, niezależnie od globalnej blokady) → 423 termination\_locked (serwer z aktywną VM przy globalnej blokadzie — także dla właściciela) → polityka usunięcia: serwer z VM — właściciel konta VM (inaczej 403 account\_owner\_required), serwer bez VM — pivot OWNER lub członek puli administratorów (inaczej 403). ## Bezpieczeństwo — co NIE trafia do odpowiedzi Selekcja pól jest jawna i celowo pomija wszystko wrażliwe: - **ServerResource** — pomija relację sshKey (zaszyfrowana para kluczy deploy public/private, ładowana na każdym zapytaniu przez Server::$with) oraz surowy blob info ze skryptu bootstrap. - **VirtualMachineResource** — nigdy nie serializuje root\_password VM (zaszyfrowane, reveal tylko dla admina), współrzędnych klastra PVE ani per-VM użytkownika Proxmox. - **ServerComponentResource** — maskuje w data\_rows klucze wyglądające na sekrety (zawierające pass, secret lub token → \*\*\*\*\*\*\*\*); akcje manage zapisują db\_pass i podobne do zaszyfrowanego bloba data, który nigdy nie wraca API-em. - **ServerOperationResource** — nie serializuje surowego bloba output (pełny JSON wyniku zadania agenta z możliwymi parametrami operacji); kontraktem API jest maszynowy status. ## API v1 — endpointy MetodaŚcieżkaScopeOpisGET/api/v1/serversinfra:readLista serwerów (własne + zaakceptowane udziały + serwery z VM bieżącego konta), paginowana; ownership. GET/api/v1/servers/{server}infra:readSzczegóły serwera (komponenty + sparowana VM). GET/api/v1/servers/{server}/statisticsinfra:readSerie CPU/RAM/dysk (ostatnie próbki z Prometheusa). GET/api/v1/servers/{server}/componentsinfra:readLista komponentów serwera i ich status. GET/api/v1/servers/{server}/components/{component}infra:readSzczegóły komponentu (scoped binding) z data\_rows. GET/api/v1/servers/{server}/operationsinfra:readHistoria operacji (instalacja, usuwanie, zarządzanie — wykonywanych przez agenta nodead), najnowsze pierwsze; simplePaginate. GET/api/v1/servers/{server}/wafinfra:readStatus WAF: has\_agent, reguły, 20 ostatnich zdarzeń. POST/api/v1/serversinfra:write**Wyłączone** — zawsze 410 foreign\_servers\_disabled (serwerów spoza chmury nodea nie można dodawać). PUT/PATCH/api/v1/servers/{server}infra:writeEdycja nazwy/portu SSH (IP niemutowalne; owner-only). POST/api/v1/servers/{server}/test-sshinfra:writeTest połączenia SSH kluczem deploy. {ok, message} lub 502. PATCH/api/v1/servers/{server}/noteinfra:writeUstawienie/wyczyszczenie notatki. POST/api/v1/servers/{server}/cloneinfra:write**Wyłączone** — po sprawdzeniu widoczności (403/404) zawsze 410 foreign\_servers\_disabled. POST/api/v1/servers/{server}/components/{component}/installinfra:writeInstalacja komponentu — wykonuje ją agent nodead zainstalowany na serwerze. Zwraca 202 + operację; gdy agent zniknie przed wysłaniem zadania, operacja kończy się statusem FAIL z powodem. 422 (pole component) z czytelnym komunikatem, gdy: komponent jest niedostępny na systemie serwera (np. php83 na Ubuntu 26.04); serwer nie ma agenta nodead („agent nodead nie jest połączony z tym serwerem — podłącz agenta”); agent jeszcze się nie zarejestrował (np. świeżo utworzona VM nodea); agent jest offline; agent nie ogłosił obsługi component.install (wymaga aktualizacji). Dotyczy każdego komponentu. POST/api/v1/servers/{server}/vm/startinfra:writeStart VM (async). 422 gdy brak sparowanej VM; 423 (service\_suspended) gdy usługa rozliczana w WHMCS jest zawieszona lub zakończona albo administrator zawiesił serwer; 409 (vm\_migrating) gdy administrator przenosi serwer na inny węzeł. POST/api/v1/servers/{server}/vm/rebootinfra:writeReboot VM (synchroniczny PVE). 422/409 (no\_pve\_assignment, vm\_migrating)/423 (service\_suspended)/502. POST/api/v1/servers/{server}/waf/rules/{rule}/toggleinfra:writeWłącz/wyłącz regułę WAF; enabled (bool). 422 bez agenta fleet. DELETE/api/v1/servers/{server}infra:deleteUsunięcie serwera + async destroy VM. Zwraca 204. Serwer z VM: tylko właściciel konta VM (403 account\_owner\_required). Serwer z aktywną VM przy globalnej blokadzie terminacji → 423 (termination\_locked). VM zarządzana w panelu rozliczeń WHMCS (ModulesGarden) → zawsze 423 (managed\_by\_whmcs). VM w trakcie migracji na inny węzeł → 409 (vm\_migrating), nic nie jest usuwane. Serwery bez VM usuwa się normalnie. POST/api/v1/servers/{server}/vm/stopinfra:deleteStop VM (destrukcyjne — wyłącza produkcyjną maszynę). 422 bez VM; 409 (vm\_migrating) w trakcie migracji na inny węzeł. Łącznie: **18 endpointów** (7 read, 9 write, 2 delete). ### GET /servers — parametry zapytania - search (string, opcjonalny, max 255) — dopasowanie po nazwie i IP. - sort (enum: name|ip|created\_at, domyślnie created\_at) — twarda whitelista. - direction (asc|desc; dla created\_at domyślnie desc). - per\_page (int 1–100, domyślnie 20), page (int ≥1). ### ServerResource — pola id (UUID), name, ip, ssh\_port, status (małe litery: new|connected|installed|error), note, ownership (owner|shared|account, tylko w index; account = serwer z VM widoczny przez członkostwo w bieżącym koncie, bez wiersza pivot), has\_virtual\_machine (bool), virtual\_machine (obiekt lub null), components\[\] (gdy załadowane), created\_at, updated\_at. Obiekt virtual\_machine: id, vm\_id (VMID Proxmox), name, ip, status, last\_error, oraz opcjonalnie plan, os\_template, location. ### POST/PATCH /servers — parametry ciała - name (string, wymagany, min 3, max 100). - ip (wymagany dla POST, ipv4; niemutowalny — nieobecny w PATCH). - ssh\_port (wymagany, numeryczny). Notatka: note (string, nullable). Toggle WAF: enabled (bool, wymagany). Instalacja: parametr URL {component} = wartość enuma Component (np. nginx, php83, mariadb1011, redis, postgres16, nodejs20). ### Kody błędów - 401 — brak/niepoprawny token. - 403 — brak scope lub istniejący, niewidoczny serwer (polityka); mutacja serwera z VM innego konta udostępnionego do monitoringu. - 403 — błąd kontekstu konta: account\_permission\_denied (pole permission podaje brakującą flagę) — products przy odczycie, manageproducts przy akcjach serwera z VM, no\_account\_context, account\_forbidden / account\_mismatch (nagłówek X-Account-Id lub przypięcie tokenu) — patrz [Konta klientów](https://nodea.pl/pl/dokumentacja-api/accounts). - 403 — account\_owner\_required: serwer z VM może usunąć tylko właściciel konta VM. - 404 — nieznany identyfikator; serwer z VM innego konta bez udziału; komponent z innego serwera (scoped binding). - 410 — foreign\_servers\_disabled: dodawanie i klonowanie serwerów jest wyłączone (serwery spoza chmury nodea). - 409 — brak przypisania PVE przy reboot (no\_pve\_assignment); start / stop / reboot VM oraz usunięcie serwera z VM, którą administrator właśnie przenosi na inny węzeł (vm\_migrating) — akcje wracają po zakończeniu migracji. - 422 — walidacja; brak sparowanej VM (no\_virtual\_machine); brak agenta fleet (no\_fleet\_agent). - 423 — usunięcie serwera, którego VM jest zarządzana w panelu rozliczeń WHMCS (moduł ModulesGarden), jest odrzucane zawsze, także przy wyłączonej blokadzie globalnej (kod managed\_by\_whmcs); serwer i VM pozostają nietknięte — usługę zamyka się w panelu rozliczeń. - 423 — usunięcie serwera z aktywną VM jest obecnie zablokowane globalnie w Nodea (kod termination\_locked); serwer i VM pozostają nietknięte. Blokada jest sprawdzana przed uprawnieniami konta. - 423 — start / reboot VM, której usługa rozliczana w WHMCS jest zawieszona (nieopłacona faktura) albo zakończona (kod service\_suspended); zatrzymanie VM pozostaje dozwolone. Blokada znika, gdy WHMCS przywróci usługę (status Active). Ten sam kod zwraca start / reboot serwera zawieszonego ręcznie przez administratora Nodea — blokadę zdejmuje tylko administrator. - 502 — nieudany test SSH / nieudany reboot (reboot\_failed). ## Przykłady — API ### Lista serwerów z sortowaniem curl -s "https://app.nodea.io/api/v1/servers?sort=name&direction=asc&per\_page=25" \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json" ### Próba dodania serwera (wyłączone) curl -s -X POST https://app.nodea.io/api/v1/servers \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json" # HTTP 410 { "message": "Nie można dodawać serwerów spoza chmury nodea. Nowe instancje obliczeniowe zamówisz w panelu.", "code": "foreign\_servers\_disabled" } ### Instalacja komponentu curl -s -X POST https://app.nodea.io/api/v1/servers/{id}/components/nginx/install \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json" ### Reboot maszyny wirtualnej curl -s -X POST https://app.nodea.io/api/v1/servers/{id}/vm/reboot \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json" ### Stop VM (destrukcyjne, scope infra:delete) curl -s -X POST https://app.nodea.io/api/v1/servers/{id}/vm/stop \\ -H "Authorization: Bearer $NODEA\_TOKEN" \\ -H "Accept: application/json" ## MCP — narzędzia (17) Narzędzia MCP dzielą model uwierzytelniania i zakresów z API v1 (Bearer + scope w ensureScope) oraz flagę features:servers. Serwery adresowane są po UUID; brakujący i niedostępny identyfikator zwracają ten sam błąd (brak enumeracji między najemcami — InteractsWithServers::serverFor deleguje do polityk view/manage). Sekrety są maskowane identycznie jak w API (ten sam kształt zasobów). Narzędzia destrukcyjne (server-delete, server-vm-stop) wymagają confirm: true. NarzędzieScopeTrybOpisservers-listinfra:readread-onlyLista serwerów (własne + udziały FOREIGN + serwery z VM bieżącego konta); search, page, per\_page (max 50). Zwraca etykietę ownership (owner|shared|account); serwery z VM innych kont użytkownika są ukryte. server-getinfra:readread-onlySzczegóły serwera (komponenty + VM). Param: id. server-statisticsinfra:readread-onlySerie CPU/RAM/dysk. Param: id. server-componentsinfra:readread-onlyLista komponentów; id, page, per\_page. Pomija komponenty niedostępne na systemie serwera oraz — gdy serwer nie ma zarejestrowanego agenta nodead z obsługą component.install — wszystkie niezainstalowane (chyba że już są na serwerze). server-operationsinfra:readread-onlyHistoria operacji; id, filtr component, paginacja. Bez surowego wyniku zadania. server-waf-statusinfra:readread-onlyStatus WAF: has\_agent, reguły, 20 ostatnich zdarzeń. Param: id. server-createinfra:write—**Wyłączone** — zawsze błąd foreign\_servers\_disabled. server-updateinfra:writeidempotentneEdycja name/ssh\_port (częściowa; IP niemutowalne). Owner-only. server-set-noteinfra:writeidempotentneUstawienie/wyczyszczenie notatki; id, note (nullable). server-test-sshinfra:writezapis (dial infra)Test SSH kluczem deploy; {connected, error}. Owner-only. server-cloneinfra:write—**Wyłączone** — po sprawdzeniu widoczności id zawsze błąd foreign\_servers\_disabled. server-component-installinfra:writezapisInstalacja komponentów; id, components\[\] (min 1, wartości enuma). Wykonuje agent nodead serwera, rozłożone co 10 s. Błąd z czytelnym powodem, gdy komponent jest niedostępny na systemie serwera albo serwer nie ma zarejestrowanego agenta nodead z obsługą instalacji (brak agenta, agent niezarejestrowany, offline albo bez capability component.install). server-vm-startinfra:writezapisStart VM; id. Błąd no\_virtual\_machine gdy brak VM; service\_suspended gdy usługa WHMCS jest zawieszona lub zakończona albo administrator zawiesił serwer; vm\_migrating gdy administrator przenosi serwer na inny węzeł. server-vm-rebootinfra:writezapisReboot VM (synchroniczny PVE); id. Błąd service\_suspended gdy usługa WHMCS jest zawieszona lub zakończona albo administrator zawiesił serwer; vm\_migrating w trakcie migracji na inny węzeł. server-waf-rule-toggleinfra:writeidempotentnePrzełączenie reguły WAF; id, rule\_id (max 64), enabled. Wysyła pełny zestaw override do agenta nodead. server-deleteinfra:deletedestrukcyjneUsunięcie serwera + async destroy VM; id + wymagane confirm: true. Serwer z VM: tylko właściciel konta VM (account\_owner\_required); serwer bez VM: właściciel (pivot OWNER) lub członek puli administratorów. Kolejność: widoczność → managed\_by\_whmcs (VM zarządzana w WHMCS — zawsze, nic nie jest usuwane) → termination\_locked (globalna blokada, nic nie jest usuwane) → polityka usunięcia → vm\_migrating (administrator przenosi VM na inny węzeł, nic nie jest usuwane). server-vm-stopinfra:deletedestrukcyjneStop VM (offline do restartu); id + wymagane confirm: true. Owner-only. Błąd vm\_migrating w trakcie migracji na inny węzeł. Podział: 6 read-only, 9 zapisujących, 2 destrukcyjne. **Konta klientów w MCP.** Serwery bez VM działają bez zmian (pivot). Serwer z VM należy do konta VM: w bieżącym koncie połączenia odczyt wymaga uprawnienia products, akcje (server-update, server-vm-start/-stop/-reboot, server-waf-rule-toggle, server-component-install, server-test-ssh, server-set-note) — products + manageproducts, a server-delete — roli właściciela konta. VM innego konta bez udziału zwraca „nie znaleziono”, a z udziałem monitoringu — tylko odczyt. Odmowy kończą się sufiksem (code: account\_permission\_denied, permission: \), (code: account\_owner\_required), (code: no\_account\_context), (code: managed\_by\_whmcs) lub (code: termination\_locked); start/reboot VM zawieszonej usługi WHMCS lub serwera zawieszonego przez administratora — (code: service\_suspended); start/stop/reboot i usunięcie serwera, którego VM administrator przenosi na inny węzeł — (code: vm\_migrating). ### Przykłady — MCP (JSON-RPC) { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "server-component-install", "arguments": { "id": "9b1f...uuid", "components": \["nginx", "php83"\] } } } { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "server-vm-stop", "arguments": { "id": "9b1f...uuid", "confirm": true } } } ## Powiązane - [Klucze SSH — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/ssh-keys) - [DNS](https://nodea.pl/pl/slownik-pojec/dns) - [Urządzenia (Connection Manager) — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/vault-devices) - [Konta klientów — API v1 i MCP | Dokumentacja Nodea](https://nodea.pl/pl/dokumentacja-api/accounts) --- Wersje językowe: [en](https://nodea.io/en/api-docs/servers.md) Spis treści witryny: [llms.txt](https://nodea.pl/pl/llms.txt)