Serwer MCP Nodea — endpoint, uwierzytelnianie, discovery OAuth, narzędzia | Nodea

Nodea udostępnia serwer MCP (Model Context Protocol) — standardowy interfejs, przez który asystenci AI (np. Claude) i inne narzędzia MCP łączą się z Twoim kontem i wykonują akcje: sprawdzają status monitoringu, tworzą monitory, zarządzają alertami, serwerami, DNS-em czy hostingiem. Pod spodem MCP korzysta z tego samego uwierzytelniania i tych samych scope'ów co REST API v1 — narzędzie dostaje dokładnie tyle uprawnień, ile ma token.

Ten wpis opisuje endpoint MCP, uwierzytelnianie, discovery OAuth dla klientów takich jak Claude, sposób, w jaki narzędzia respektują scope'y i polityki, listę modułów oraz adnotacje bezpieczeństwa. Jeśli dopiero zaczynasz, zacznij od wprowadzenia do API.

Endpoint

Serwer MCP działa pod jednym adresem, w transporcie Streamable HTTP (JSON-RPC 2.0 po HTTP POST):

POST https://app.nodea.io/mcp

Klient MCP wysyła tam żądania JSON-RPC 2.0 (initialize, tools/list, tools/call itd.). Endpoint jest chroniony tym samym guardem Passport co API v1, więc każde żądanie musi nieść ważny token Bearer.

Uwierzytelnianie

MCP używa tego samego Personal Access Tokenu co REST API — generujesz go w panelu w sekcji Tokeny API (/app/account/api-tokens) i dołączasz w nagłówku:

Authorization: Bearer 1|AbCdEf0123456789...

Aby połączyć się z transportem MCP, token musi mieć scope mcp:use. Ważne: mcp:use daje wyłącznie dostęp do transportu — sam nie odblokowuje żadnych danych. Każde narzędzie dodatkowo wymaga właściwego scope'a modułowego (np. monitoring:read, żeby wylistować strony). Token z samym mcp:use połączy się z serwerem, ale każda próba użycia narzędzia bez odpowiedniego scope'a zostanie odrzucona.

Discovery OAuth dla klientów AI (Claude)

Klienci tacy jak Claude nie wymagają ręcznego wklejania tokenu — potrafią same się onboardować przez OAuth. Serwer publikuje metadane discovery zgodne z RFC 9728 / RFC 8414:

• GET /.well-known/oauth-protected-resource — metadane chronionego zasobu (wskazuje serwer autoryzacji).
• GET /.well-known/oauth-authorization-server — metadane serwera autoryzacji (endpointy authorize/token).

Gdy niezalogowany klient trafi na /mcp, dostaje 401 z nagłówkiem WWW-Authenticate: Bearer … resource_metadata="…", który kieruje go do dokumentu discovery — dzięki temu klient wie, gdzie się autoryzować.

Nowi klienci rejestrują się przez Dynamic Client Registration (RFC 7591):

POST https://app.nodea.io/oauth/register

Rejestracja tworzy publicznego klienta OAuth typu authorization-code z PKCE. Dozwolone są tylko zaufane adresy przekierowań (callbacki oficjalnych konektorów Claude — https://claude.ai i https://claude.com); endpoint rejestracji jest ograniczony limitem zapytań, żeby zapobiec spamowaniu rejestracji. Po autoryzacji klient otrzymuje token, który — dla dostępu do danych — musi nieść odpowiednie scope'y modułowe obok mcp:use.

Jak narzędzia respektują scope'y i polityki

Każde narzędzie MCP przed wykonaniem akcji sprawdza dwie rzeczy:

1. Scope tokenu — narzędzie odczytujące monitoring wymaga monitoring:read, tworzące/edytujące — monitoring:write, usuwające — monitoring:delete. Brak scope'a = odmowa (bez wykonania akcji).
2. Polityki własności (Policies) — dokładnie te same, co w panelu i REST API. Narzędzie widzi i modyfikuje wyłącznie zasoby należące do właściciela tokenu; cudzych zasobów nie dotknie, nawet z poprawnym scope'em.

Dodatkowo obowiązują te same flagi funkcji (Pennant) co w panelu — jeśli moduł jest wyłączony dla Twojego konta, powiązane narzędzia są niedostępne.

Moduły narzędzi

Serwer MCP wystawia około 110 narzędzi, pogrupowanych w moduły odpowiadające obszarom panelu:

• Monitoring — websites, heartbeats, reports, status-pages.
• Alerting — integrations, notification-groups, escalation-policies, shares.
• Infrastruktura — servers, ssh-keys, dns, vault-devices.
• Konto — profile, tickets, billing, domains, hosting, migrations.

Każde narzędzie niesie własny opis i schemat argumentów, które klient MCP odczytuje przez tools/list. Mapowanie na scope'y jest identyczne jak w REST API: moduł monitoringu → grupa monitoring, alertów → alerting, infrastruktury → infra, konta → account.

Adnotacje: read-only i destructive

Narzędzia są oznaczone adnotacjami, żeby klient (i człowiek zatwierdzający) wiedział, co dana akcja robi:

• read-only — narzędzie tylko odczytuje dane (listy, szczegóły, statusy). Bezpieczne do wywołania bez dodatkowego potwierdzenia.
• destructive — narzędzie wykonuje akcję nieodwracalną (usunięcie monitora, zatrzymanie VM, terminacja hostingu, przywrócenie backupu). Takie narzędzia wymagają jawnego potwierdzenia: argument confirm: true. Bez niego wywołanie zostaje odrzucone z czytelnym komunikatem — dzięki temu asystent nie skasuje zasobu „przy okazji", bez świadomej zgody.

Jak podłączyć Claude

W Claude dodajesz konektor MCP, wskazując URL serwera:

https://app.nodea.io/mcp

Claude sam wykryje discovery OAuth (/.well-known/oauth-protected-resource), przeprowadzi rejestrację klienta i flow autoryzacji, a Ty w oknie zgody zatwierdzisz zakres uprawnień. Po połączeniu Claude widzi listę narzędzi (tools/list) i może wykonywać akcje w granicach przyznanych scope'ów — z zachowaniem potwierdzenia confirm: true dla akcji nieodwracalnych. Alternatywnie możesz podać gotowy Personal Access Token (z mcp:use plus potrzebnymi scope'ami modułowymi), jeśli klient obsługuje ręczne wklejenie tokenu Bearer.