Skip to Content
Tworzenie aplikacji IoTAPIPunkt końcowy MCP

Punkt końcowy MCP

IronFlock jest serwerem MCP. Claude i każdy inny klient, który obsługuje Model Context Protocol, może wyświetlać twoje projekty, odczytywać ich urządzenia, aplikacje i dane oraz działać na nich za pomocą narzędzi, które oferuje IronFlock, w granicach tego, na co pozwala twój klucz API. Punkt końcowy jest częścią tej samej usługi API co REST API i używa tych samych kluczy API.

Adres i uwierzytelnianie

URL w chmurze IronFlockhttps://api.ironflock.com/mcp
URL na Appliancehttps://api. z dopisaną domeną Appliance, a potem /mcp, gdy tylko Appliance uruchamia usługę IronFlock API
TransportStreamable HTTP
UwierzytelnianieAuthorization: Bearer <your API key>

Utwórz klucz API w Studio zgodnie z opisem w Tworzenie klucza API. Każde żądanie niesie klucz. Żądanie bez klucza albo z kluczem, który nie jest ważny (usunięty, wygasły lub z innego IronFlock), otrzymuje odpowiedź HTTP 401. Serwer nie oferuje logowania przez przeglądarkę (OAuth): klucz jest jedynym sposobem dostępu.

Serwer nie przechowuje sesji. Każde żądanie jest obsługiwane osobno, więc klient może się swobodnie łączyć, rozłączać i łączyć ponownie. Na każde żądanie odpowiada jedną treścią JSON i nie ma strumienia zdarzeń, którego można by nasłuchiwać.

Połącz Claude

Klucz wpisujesz sam, w ustawieniach samego Claude. Nigdy nie wklejaj go do czatu.

Claude Code

Claude Code łączy się przez wtyczkę ironflock, która deklaruje serwer MCP IronFlock. Działa w terminalu, w rozszerzeniach IDE i w karcie Code aplikacji desktopowej Claude.

  1. Dodaj marketplace i zainstaluj wtyczkę w sesji Claude Code:

    /plugin marketplace add IronFlock/agent-skills /plugin install ironflock@ironflock
  2. Instalacja otwiera okno dialogowe z dwoma ustawieniami. IronFlock API address to https://api.ironflock.com dla chmury, a dla Appliance https://api. z dopisaną domeną Appliance, w obu przypadkach bez /mcp i bez ukośnika na końcu. IronFlock API key to klucz ze Studio. Claude Code przechowuje go w bezpiecznym magazynie poświadczeń systemu, a nie w pliku ustawień.

  3. Uruchom ponownie Claude Code. /mcp pokazuje wtedy serwer plugin:ironflock:ironflock jako połączony.

Ustawienia zmienisz później przez /plugin configure ironflock@ironflock i ponowne uruchomienie Claude Code. Dopóki klucz nie jest ustawiony, serwer się nie uruchamia. Instalacja z powłoki (claude plugin install) nie otwiera okna dialogowego, więc dokończ ją przez /plugin configure ironflock@ironflock w sesji. Twórz z Claude Code opisuje wtyczki i ich umiejętności.

Claude w przeglądarce, na komputerze i telefonie oraz Cowork

Własne połączenie wtyczki działa tylko w Claude Code. W czacie aplikacji Claude i w Cowork dodajesz IronFlock jeden raz jako niestandardowy konektor z kluczem w nagłówku żądania. Nagłówki żądań w niestandardowych konektorach to funkcja beta dostępna dla ograniczonej grupy organizacji. Jeśli okno dialogowe poniżej nie ma sekcji Request headers, twoja organizacja jeszcze jej nie ma i IronFlock nie da się tam na razie podłączyć: Claude Code działa.

  1. Otwórz Customize > Connectors, wybierz Add, a potem Add custom connector.
  2. Wpisz nazwę IronFlock i URL serwera https://api.ironflock.com/mcp.
  3. Ustaw Authentication na No sign-in.
  4. W sekcji Request headers dodaj nagłówek Authorization z wartością Bearer i twoim kluczem: słowo Bearer, jedna spacja, potem klucz. Bez Bearer IronFlock odrzuca żądanie.
  5. Wybierz Add.

W planach Team i Enterprise konektor dodaje właściciel w Organization settings > Connectors, Add, a potem Custom; nagłówki żądań mogą być w Advanced. Każdy, kto używa tego konektora, działa z tym jednym kluczem, który wpisał właściciel, więc daj mu tylko te uprawnienia i projekty, z których wszyscy mogą korzystać.

Nagłówków żądań konektora nie można edytować: aby zmienić klucz, usuń konektor i dodaj go ponownie. Konektor łączy się z serwerów Anthropic, więc adres musi być osiągalny z internetu. Tak jest w przypadku chmury. Appliance, do którego dociera tylko sieć twojej firmy, zwykle nie da się tam podłączyć, natomiast Claude Code na komputerze w tej sieci tak.

Inni klienci MCP

Każdy klient, który obsługuje Streamable HTTP i nagłówek żądania, łączy się za pomocą URL i nagłówka Authorization: Bearer <your API key>. Nie umieszczaj klucza w plikach, które udostępniasz lub commitujesz.

Sprawdź połączenie

Poproś Claude o wylistowanie twoich projektów IronFlock, a potem urządzeń jednego z nich. Claude wywołuje list_projects i list_devices, które tylko odczytują.

Narzędzia

Serwer oferuje 33 narzędzia w tych obszarach. Większość z nich działa w jednym projekcie i przyjmuje jego swarm_key, który podaje list_projects. Narzędzie, które coś zmienia lub usuwa, jest odpowiednio oznaczone, aby klienci tacy jak Claude mogli zapytać cię przed jego wywołaniem.

Projekty

NarzędzieUprawnienieCo robi
list_projectsdevices:readWyświetla projekty, w których klucz może pracować

Urządzenia

NarzędzieUprawnienieCo robi
list_devicesdevices:readWyświetla urządzenia projektu, aplikacje zainstalowane na każdym z nich, czy działają i czy urządzenie jest online
create_devicedevices:writeTworzy urządzenie w projekcie i odpowiada jego kluczem i nazwą
delete_devicedevices:writeTrwale usuwa urządzenie z projektu

Aplikacje w projekcie

NarzędzieUprawnienieCo robi
list_project_appsapps:readWyświetla aplikacje zainstalowane w projekcie i na ilu urządzeniach działa każda z nich
check_app_statusapps:readPokazuje, czy aplikacja działa na swoich urządzeniach i czy docierają jej dane
install_appapps:writeInstaluje aplikację ze sklepu w projekcie i opcjonalnie na urządzeniach
set_app_stateapps:writeUruchamia lub zatrzymuje zainstalowaną aplikację na urządzeniach
update_appapps:writeAktualizuje zainstalowaną aplikację do jej najnowszego wydania
uninstall_appapps:writeUsuwa aplikację z urządzeń albo z całego projektu

Sklep z aplikacjami i koszty

NarzędzieUprawnienieCo robi
search_appsapps:readPrzeszukuje sklep z aplikacjami według możliwości i zwraca pasujące aplikacje z ich cenami
get_app_detailsapps:readOdczytuje opis, README i cenę od jednej do trzech aplikacji ze sklepu
get_install_quoteapps:readSprawdza, ile kosztowałaby instalacja aplikacji i co by ją uniemożliwiło
estimate_project_costapps:readSzacuje roczny koszt konfiguracji projektu; nic nie jest kupowane
sync_app_to_storeapps:writeTylko na Appliance: kopiuje aplikację ze sklepu chmury IronFlock do własnego sklepu Appliance

Dane

NarzędzieUprawnienieCo robi
get_schemadata:readOpisuje bazę danych projektu: jej tabele, widoki i kolumny
execute_sqldata:readWykonuje jedno zapytanie SELECT tylko do odczytu na bazie danych projektu
list_dashboardsdata:readWyświetla dashboardy projektu
list_app_filesdata:readWyświetla i przeszukuje pliki, które aplikacja przechowuje w projekcie
read_app_filedata:readOdczytuje jeden plik przechowywany przez aplikację: tekst, obraz lub inny plik
save_transformdata:writeTworzy lub zastępuje niestandardową transformację, która utrzymuje aktualną wartość pochodną dla paneli
delete_transformdata:writeTrwale usuwa niestandardową transformację

Alarmy

NarzędzieUprawnienieCo robi
list_alarmsalarms:readWyświetla alarmy projektu z ich stanem, wyzwalaczami i odbiorcami
create_alarmalarms:writeTworzy alarm, który obserwuje tabelę danych aplikacji
update_alarmalarms:writeZmienia wyzwalacz lub odbiorców alarmu albo go wstrzymuje i wznawia
delete_alarmalarms:writeTrwale usuwa alarm i jego historię

Logi i dziennik audytu

NarzędzieUprawnienieCo robi
get_app_logslogs:readOdczytuje własne logi aplikacji z urządzeń, na których działa
get_device_logslogs:readOdczytuje, co robiło samo urządzenie: aplikacje, pobierania, dysk, sieć, aktualizacje agenta
query_audit_loglogs:readWykonuje jedno zapytanie tylko do odczytu na dzienniku audytu: kto i kiedy zmienił projekt, jego urządzenia, grupy i aplikacje
get_appliance_healthdevices:readTylko na Appliance: sprawdza stan własnych usług platformy Appliance, dysku, pamięci, licencji i aktualizacji
get_appliance_logslogs:readTylko na Appliance: odczytuje log jednej części platformy Appliance

Narzędzia aplikacji

Aplikacje dostarczają własne narzędzia razem ze swoimi agentami AI: funkcje aplikacji, które działają na urządzeniu, na przykład odczyt stanu maszyny lub zmiana ustawienia. Docierają do nich dwa narzędzia.

NarzędzieUprawnienieCo robi
list_app_toolsapptools:callWyświetla narzędzia zainstalowanej aplikacji wraz z ich argumentami i instrukcjami agentów aplikacji
call_app_toolapptools:callUruchamia jedno z nich na jednym urządzeniu projektu

call_app_tool działa na urządzeniu, a narzędzie aplikacji może tam coś zmienić. Urządzenie musi być jednym z urządzeń projektu, które widzi właściciel klucza, a właściciel potrzebuje prawa do korzystania z danych aplikacji, tak jak przy obsłudze aplikacji z jej panelu. Aplikacja otrzymuje dokładnie podane argumenty i nic więcej. Wyświetlane są tylko narzędzia zainstalowanego wydania, a nie wersji deweloperskiej aplikacji. Teksty narzędzia pisze deweloper aplikacji i są one przycinane do stałej długości.

Uprawnienia

Każde narzędzie wymaga jednego uprawnienia podanego w tabelach powyżej. Serwer oferuje klientowi tylko narzędzia, których klucz może używać, a każde inne narzędzie odrzuca tak, jakby nie istniało. Cokolwiek klucz dopuszcza, narzędzie nigdy nie robi więcej, niż właściciel klucza może zrobić w IronFlock. releases:publish nie ma narzędzia: służy operacjom REST, które budują wydania. Wszystkie uprawnienia opisuje sekcja Uprawnienia, a to, jak wybrać je w Studio, sekcja Tworzenie klucza API.

Klucz ograniczony do projektów widzi tylko te projekty. Kluczowi ograniczonemu do jednej aplikacji oferowane są tylko narzędzia, które działają dla aplikacji, a więc nie list_projects. Żadnemu z nich nie są oferowane narzędzia wykraczające poza jeden projekt: query_audit_log, którego zapytanie może wymieniać zasoby dowolnego projektu, który właściciel może odczytać, dwa narzędzia Appliance, które nie należą do żadnego projektu, oraz sync_app_to_store, który zmienia sklep Appliance dla wszystkich.

Niektóre narzędzia mają dodatkowe zasady:

  • install_app przyjmuje odpowiedź get_install_quote, która została ci pokazana, i nic nie instaluje, gdy cena lub cokolwiek innego w tej wycenie zmieniło się od tamtej chwili. Instalacja płatnej aplikacji kosztuje pieniądze.
  • set_app_state i update_app zmieniają najwyżej 10 urządzeń w jednym wywołaniu.
  • create_device odpowiada kluczem i nazwą nowego urządzenia, a nigdy jego plikiem konfiguracyjnym, który zawiera poświadczenia urządzenia. Pobierz plik w Studio, w ustawieniach urządzenia w Konserwacja > Plik konfiguracyjny urządzenia > Pobierz plik konfiguracyjny, albo skonfiguruj urządzenie na maszynie przez ironflock agent install --project <project> --name <name>, które tworzy urządzenie i zostawia plik na maszynie (Logowanie i zarządzanie urządzeniami).
  • Projekt zapisuje jedną niestandardową transformację naraz. Drugie save_transform, gdy pierwsze trwa, jest odrzucane.
  • Konto może uruchamiać query_audit_log raz naraz i sześć razy na minutę, ponieważ baza danych za nim jest współdzielona.
  • Zmiana, która nie zakończy się w czasie swojego wywołania, może mimo to zostać wykonana. Wynik o tym mówi, a narzędzie jej nie powtarza.

Wyniki

Wynik to JSON, jako treść strukturalna i jako ten sam JSON w bloku tekstowym. Długa lista jest przycinana do 50 000 znaków, a jej pole cut mówi, ile wpisów pominięto i jak czytać dalej. Obrazy (PNG, JPEG, GIF i WebP) przychodzą jako obrazy, a inne pliki, na przykład PDF, jako osadzone zasoby z ich typem multimediów.

Gdy narzędzie nie może zrobić tego, o co poproszono, jego wynik jest oznaczony jako błąd i w jednym zdaniu mówi, dlaczego, na przykład że projekt nie istnieje albo że platforma nie odpowiedziała na czas.

Limity

To są wartości domyślne, na klucz API:

Limit
Żądania120 na minutę, w seriach do 30
Żądania otwarte jednocześnie8
Treść żądania1 114 112 bajtów: 1 MiB argumentów i otaczającej je wiadomości
Jedno wywołanie narzędzia90 sekund
Zapytanie do bazy danych30 sekund; execute_sql zwraca 100 wierszy, chyba że poprosisz o więcej, najwyżej 1000
Jeden wynik50 000 znaków; wynik call_app_tool jest przycinany przy 45 000

Błędy

OdpowiedźZnaczenieCo zrobić
401Klucza brakuje, jest błędnie wpisany lub ucięty, usunięty, wygasły albo pochodzi z innego IronFlock. W konektorze może brakować Bearer Utwórz nowy klucz w Studio tego IronFlock, z którym się łączysz, i wpisz go ponownie
404 pod /mcp/mcp występuje w adresie dwa razy albo instancja nie oferuje jeszcze punktu końcowego, na przykład Appliance, który nie uruchamia usługi IronFlock APIPopraw adres; w przeciwnym razie użyj chmury
405GET i DELETE pod /mcp: serwer nie ma strumienia zdarzeń ani sesji do zakończeniaUżyj POST
413Treść żądania jest zbyt dużaWysyłaj mniej w jednym wywołaniu
429Klucz wysłał zbyt wiele żądań albo ma zbyt wiele otwartych jednocześnie. Nagłówek Retry-After mówi, ile sekund czekaćOdczekaj tyle i kontynuuj z mniejszą liczbą jednoczesnych wywołań
503Platforma jest w tej chwili niedostępna albo usługa się wyłączaSpróbuj ponownie za minutę
504Platforma nie odpowiedziała na czasSpróbuj ponownie za minutę

Narzędzie, które nie może zrobić tego, o co poproszono, nie odpowiada błędem HTTP: jego wynik jest oznaczony jako błąd i w jednym zdaniu wyjaśnia, co poszło nie tak.

Chroń swój klucz

  • Nigdy nie wklejaj klucza do czatu. Jeśli tak się stało, jest on częścią tej rozmowy: usuń klucz w Studio, utwórz nowy i wpisz go w ustawieniach.
  • Studio pokazuje nowy klucz tylko raz, przy jego tworzeniu. Od razu zapisz go w ustawieniach klienta.
  • Używaj osobnego klucza dla każdego miejsca, które go używa, aby móc usunąć jeden, nie psując pozostałych, i usuwaj klucze, których już nie używasz. Klucz jest ważny przez rok.
  • Dawaj kluczowi tylko te uprawnienia i projekty, których potrzebuje Claude: klucz z wyborem Wszystko i Wszystkie moje projekty pozwala Claude zrobić wszystko, co ty możesz zrobić w IronFlock. Narzędzia, które coś zmieniają lub usuwają, są odpowiednio oznaczone, aby klienci tacy jak Claude mogli najpierw zapytać cię o zgodę. Zanim się zgodzisz, przeczytaj, co Claude zamierza zmienić.
  • Konektor udostępniony przez organizację działa z jednym kluczem dla wszystkich jej użytkowników. Użyj klucza konta, które widzi tylko to, co mogą widzieć oni wszyscy.
Last updated on