Serwer MCP

Co robi serwer MCP

Model Context Protocol (MCP) to otwarty standard, który umożliwia asystentom AI wywoływanie narzędzi w innych systemach. Serwer MCP Nomid pozwala asystentom takim jak claude.ai, ChatGPT, Claude Code, Codex czy Cursor odpowiadać na pytania dotyczące floty w języku naturalnym — na przykład ile urządzeń korzysta z danej zasady lub które urządzenia nie były widziane od określonej daty — bez konieczności otwierania portalu. Może również diagnozować, dlaczego nie można zdalnie połączyć się z urządzeniem, generować łącza do urządzenia, zasady lub aplikacji w portalu, a także sprawdzać publiczne plany i ceny katalogowe Nomid. Z dodatkowym uprawnieniem może wysyłać polecenia do jednego urządzenia naraz (np. zablokowanie, ponowne uruchomienie czy zmiana zasady) lub tworzyć kody QR do aprowizacji. Osobne uprawnienie zezwala na polecenia niszczące, takie jak wyczyszczenie danych (wipe).

Endpoint i transport

POST https://api.nomid.tech/emm/api/mcp

Serwer korzysta z MCP Streamable HTTP w trybie bezstanowym. Każde wywołanie JSON-RPC jest niezależnym żądaniem HTTPS, więc nie trzeba utrzymywać sesji ani otwartego strumienia zdarzeń.

Połącz się za pomocą Sign in with Nomid (OAuth) lub klucza API. Prześlij klucz API jako token bearer lub w nagłówku X-API-Key. Większość klientów MCP obsługuje wyłącznie formę tokena bearer. Brakujący, nieprawidłowy lub wygasły klucz albo token zwraca błąd 401.

Klucz API lub połączenie Sign in with Nomid jednoznacznie określa firmę. Żadne narzędzie nie przyjmuje argumentu dzierżawcy (tenant) ani firmy, a połączenie widzi wyłącznie urządzenia i zasady własnej firmy.

Sign in with Nomid

Logowanie za pomocą Nomid (Sign in with Nomid) to mechanizm OAuth dla klientów MCP, dostępny dla każdej firmy. Zamiast korzystać z klucza, użytkownik loguje się do usługi Nomid w przeglądarce i zatwierdza uprawnienia asystenta. Następnie asystent działa w imieniu tego użytkownika w danej firmie i widzi tylko te urządzenia oraz zasady, na które pozwalają rola użytkownika i jego uprawnienia do zasad.

claude.ai, ChatGPT i Claude Code łączą się za pomocą Sign in with Nomid: dodaj powyższy adres URL punktu końcowego jako niestandardowy łącznik lub serwer MCP, bez klucza, a następnie zaloguj się, gdy klient o to poprosi. Poniższe przykłady dla Codex i Cursor używają klucza API.

W Claude Code dodaj serwer bez nagłówka, a następnie uruchom polecenie /mcp w Claude Code i wybierz serwer, aby się zalogować.

claude mcp add --transport http nomid-mdm https://api.nomid.tech/emm/api/mcp

Połączenie przenosi zakresy OAuth, które zastępują uprawnienia klucza API.

Klienci domyślnie proszą o mcp:read, mcp:devices:command i mcp:provisioning. Zakresy mcp:devices:destructive i mcp:policies:write nigdy nie są żądane automatycznie: klient musi poprosić o nie jawnie.

Na stronie zgody użytkownik może odznaczyć zakresy, a Nomid odrzuca każdy zakres, na który nie pozwala rola użytkownika lub firmowe ustawienia dostępu agentów AI. Zatwierdzenie zakresu poleceń, poleceń destrukcyjnych lub zmiany zasad wymaga niedawnego zalogowania się.

Każde żądanie ponownie weryfikuje połączenie. Jeśli użytkownik utraci dostęp do firmy lub uprawnienia roli wymagane przez narzędzie, bądź jeśli firma wyłączy dostęp agentów AI, żądania będą odrzucane tak długo, jak trwa ten stan.

Utwórz klucz API

Serwer MCP korzysta z tych samych kluczy API co REST API. Utwórz dedykowany klucz dla każdego asystenta, aby móc go unieważnić bez wpływu na inne integracje.

1. 1

   W portalu Nomid otwórz Ustawienia i wybierz zakładkę API.

2. 2

   Kliknij Utwórz klucz API i wprowadź nazwę identyfikującą asystenta, na przykład Claude Code tylko do odczytu.

3. 3

   Wybierz uprawnienia opisane poniżej. Jeśli chcesz, aby klucz przestał działać po określonym czasie, ustaw datę wygaśnięcia.

4. 4

   Skopiuj klucz, gdy zostanie wyświetlony. Zostanie pokazany tylko raz.

Połącz swojego asystenta

Zapisz klucz w zmiennej środowiskowej o nazwie NOMID_API_KEY i nigdy nie zatwierdzaj go do repozytorium. Adres URL w każdym przykładzie to produkcyjny punkt końcowy.

claude mcp add --transport http nomid-mdm https://api.nomid.tech/emm/api/mcp \
  --header "Authorization: Bearer ${NOMID_API_KEY}"

[mcp_servers.nomid]
url = "https://api.nomid.tech/emm/api/mcp"
bearer_token_env_var = "NOMID_API_KEY"

{
  "mcpServers": {
    "nomid-mdm": {
      "url": "https://api.nomid.tech/emm/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:NOMID_API_KEY}"
      }
    }
  }
}

Dostępne narzędzia

Każde narzędzie ma zakres powiązany z firmą przypisaną do klucza lub połączenia. Urządzenie jest identyfikowane przez assetId, czyli pathName zwracane przez search_devices i get_device. Zasada jest identyfikowana przez policyId, czyli pathName zwracane przez list_policies.

Narzędzia do odczytu

Narzędzia do odczytu nigdy niczego nie zmieniają. Większość zwraca te same dane, co odpowiadające im punkty końcowe REST. diagnose_device, get_portal_link, search_nomid_site oraz argument query funkcji search_devices nie mają odpowiedników w REST.

Narzędzia poleceń

Narzędzia poleceń działają na dokładnie jednym fizycznym urządzeniu na wywołanie. Nie ma opcji operacji zbiorczych. Każde narzędzie wymaga uprawnienia DEVICES_COMMAND, a change_device_policy wymaga również POLICIES_READ.

Narzędzia komend niszczących

Klienci MCP łączący się za pomocą Sign in with Nomid zamiast klucza API wymagają zakresu mcp:devices:destructive dla tych narzędzi oraz mcp:devices:command dla narzędzi poleceń.

Które urządzenia mogą odbierać polecenia

• Tylko zarejestrowane urządzenia mogą odbierać polecenia (ze statusem ACTIVE, INACTIVE lub SYNCHRONIZING). Usunięte, ponownie skonfigurowane oraz wyrejestrowane zasoby są odrzucane.
• Niektóre polecenia działają tylko na jednym typie urządzeń. Lock, lost mode, clear_app_data, reset_screen_lock oraz change_screen_lock_password wymagają urządzenia z Android Management (zarządzanego przez Google). sync_policy, shutdown_device i launch_app wymagają urządzenia zarządzanego przez agenta Nomid (AOSP). W przypadku innych urządzeń narzędzie zgłasza błąd.
• Wiadomość to powiadomienie push wysyłane do agenta Nomid na urządzeniu, dlatego urządzenie musi mieć zarejestrowany token push.
• Zasób należący do innej firmy zachowuje się dokładnie tak, jak zasób, który nie istnieje.

Niedostępne za pośrednictwem MCP ani REST API: rozpoczynanie sesji zdalnego dostępu oraz wyświetlanie lub unieważnianie tokenów rejestracji. Kod QR do obsługi administracyjnej tworzy własny token rejestracji. Zmiany zasad mają własny przepływ proponowania i zatwierdzania (propose-and-apply).

Narzędzie aprowizacji

Każde wywołanie tworzy nowy token rejestracji, dlatego asystent powinien generować kod QR tylko na wyraźną prośbę użytkownika i nigdy nie używać ponownie starszego kodu.

Kod QR jest zwracany jako blok obrazu MCP obok wyniku tekstowego, dzięki czemu klient może wyświetlić go użytkownikowi. Wynik tekstowy zawiera policyId, policyName, personalUsage, expiresAt oraz, jeśli podano sieć, wifiSsid. Nigdy nie zawiera tokena rejestracji ani hasła Wi-Fi.

Połączenia Sign in with Nomid wymagają zakresu mcp:provisioning oraz firmowego ustawienia aprowizacji w sekcji dostępu agentów AI. Klucz API z uprawnieniem PROVISIONING nie wymaga tego ustawienia.

API kodów QR do aprowizacji

Bezpieczeństwo i audyt

Polecenie zmienia coś, co człowiek trzyma w ręku. Traktuj każde z nich jako działanie wymagające decyzji człowieka.

• Zawsze potwierdzaj z użytkownikiem przed wykonaniem jakiegokolwiek polecenia. Opisy narzędzi proszą model o takie działanie, ale serwer tego nie wymusza. Zostaw włączone zatwierdzanie poszczególnych narzędzi w swoim kliencie dla narzędzi wykonujących polecenia, zamiast zatwierdzać je automatycznie.
• Nigdy nie wysyłaj polecenia ponownie po niepotwierdzonym wyniku. Jeśli wynik jest nieznany, sprawdź list_device_commands po tym, jak urządzenie miało czas na odpowiedź, i zapytaj użytkownika przed ponownym wysłaniem. Ponowne wysłanie może zduplikować polecenie, które zostało już dostarczone, a wiadomość wyświetli drugie powiadomienie.
• Wynik informujący, że polecenie nie zostało wysłane, można bezpiecznie ponowić. Polecenie nigdy nie opuściło Nomid.
• Każde polecenie jest rejestrowane w historii poleceń urządzenia w portalu Nomid. Polecenie wysłane za pomocą klucza API jest przypisywane do klucza, a nie do osoby: wpis zawiera api-key, identyfikator klucza oraz prefiks klucza. Polecenie wysłane za pośrednictwem połączenia Sign in with Nomid jest przypisywane do użytkownika, który się zalogował. Historia zwracana przez list_device_commands zawiera tylko type, status, sygnatury czasowe i outcome, bez informacji o tym, kto wysłał polecenie.
• Jeśli komputer lub plik konfiguracyjny zostanie naruszony, unieważnij klucz w Ustawienia, API. Unieważnionych kluczy nie można przywrócić. Aby zakończyć połączenie Sign in with Nomid, unieważnij je na liście połączeń na stronie agentów AI w portalu lub odłącz je w kliencie, który unieważnia tokeny przy odłączeniu. W obu przypadkach połączenie i wszystkie jego tokeny natychmiast przestają działać. Każdy użytkownik może unieważnić własne połączenia, a użytkownik, który może zarządzać kluczami API, może unieważnić dowolne połączenie w firmie.

Limity szybkości (Rate limits)

Limity są naliczane na klucz API lub na połączenie Sign in with Nomid w stałych oknach jednominutowych. Po przekroczeniu limitu żądań MCP serwer odpowiada kodem HTTP 429 Too Many Requests z nagłówkiem Retry-After wskazującym liczbę sekund do zresetowania okna.

Wywołanie narzędzia poleceń, każde wywołanie propose lub apply narzędzia do zmiany zasad oraz każde wywołanie create_provisioning_qr_code liczą się do obu limitów. Gdy takie wywołanie przekroczy współdzielony limit zapisu, serwer zwraca błąd narzędzia zamiast kodu HTTP 429. Jest to normalna odpowiedź oznaczona jako błąd, a jej treść informuje, ile sekund należy odczekać. Punkty końcowe odczytu REST nie korzystają z limitu MCP.

Rozwiązywanie problemów

Powiązana dokumentacja

• Uwierzytelnianie za pomocą klucza API
• Dokumentacja API poleceń urządzeń
• API zmian zasad
• API kodów QR do aprowizacji