Połączenie asystenta AI (MCP)

Jak pozwolić Claude, ChatGPT lub innemu agentowi pracować z Norką przez Model Context Protocol.

Norka obsługuje protokół MCP (Model Context Protocol). Po połączeniu asystenta można go zapytać „kto przyjeżdża w piątek?” albo poprosić „zarezerwuj Apartament 2 dla Nováków od 3 do 7 sierpnia”, a on to zrobi, z tymi samymi zasadami i powiadomieniami co aplikacja.

Adres serwera jest taki sam dla wszystkich klientów:

https://mcp.mojenorka.cz/mcp

1. Utworzenie tokenu API

W Norce otworzyć Ustawienia → Tokeny API i kliknąć Utwórz token.
Nazwać token według miejsca, w którym będzie używany (na przykład „Claude Desktop”), i wybrać zakres:

Zakres	Co asystent może robić
odczyt	widzieć kalendarz, pobyty, gości, nieopłacone pobyty i konfigurację
zapis	dodatkowo rezerwować i zmieniać pobyty, przypisywać sprzątanie, wysyłać link do zameldowania
zarządzanie	dodatkowo zmieniać konfigurację: obiekty, kody do drzwi, sezony, kalendarze

Token wyświetla się tylko raz. Należy go skopiować; Norka przechowuje wyłącznie jego skrót. Token można w każdej chwili unieważnić.

Najlepiej zacząć od zakresu odczyt. Zapis lub zarządzanie warto nadać tokenowi dopiero wtedy, gdy wiadomo, do czego asystent go używa.

2. Dodanie serwera do klienta

Token wysyła się jako zwykły nagłówek Authorization: Bearer ….

Claude Desktop

Otworzyć Settings → Developer → Edit Config i dodać:

{
  "mcpServers": {
    "norka": {
      "url": "https://mcp.mojenorka.cz/mcp",
      "headers": { "Authorization": "Bearer nrk_…" }
    }
  }
}

Uruchomić ponownie Claude Desktop. Norka pojawi się wśród narzędzi.

Claude Code

claude mcp add --transport http norka https://mcp.mojenorka.cz/mcp \
  --header "Authorization: Bearer nrk_…"

ChatGPT, Cursor i inne

W ustawieniach klienta dodać zdalny serwer MCP (czasem nazywany konektorem) z powyższym adresem i nagłówkiem Authorization. Dokładne kroki różnią się w zależności od klienta, ale te dwie wartości w zupełności wystarczą.

Sprawdzenie, czy działa

Poprosić asystenta: „Wywołaj whoami.” Odpowie, w imieniu której przestrzeni roboczej działa token i jakie ma narzędzia.

3. Co potrafi asystent

Narzędzia, które widzi asystent, zależą od zakresu tokenu. Wybór:

Narzędzie	Zakres	Co robi
`get_movements`	odczyt	kto danego dnia przyjeżdża, a kto wyjeżdża
`check_availability`	odczyt	które obiekty są wolne na pobyt i co stoi na przeszkodzie
`search_reservations`	odczyt	pobyty według daty, obiektu, statusu lub nazwiska
`get_reservation`	odczyt	jeden pobyt w całości, łącznie z kodem do drzwi
`list_guests`	odczyt	kto jest na pobycie
`get_estate_statistics`	odczyt	przychody i obłożenie obiektu według miesięcy
`get_estate_pricing`	odczyt	cennik obiektu: cena podstawowa, ceny sezonowe, reguły cenowe i nadchodzący rok noc po nocy
`get_price_quote`	odczyt	ile według cennika kosztuje pobyt w podanym terminie
`list_unpaid`	odczyt	nieopłacone pobyty, w tym przeterminowane
`get_attention`	odczyt	co wymaga działania teraz
`preview_transfer`	odczyt	co zmieniłoby przeniesienie pobytu do innego apartamentu
`list_collisions`	odczyt	dwa pobyty zajmujące ten sam obiekt
`list_inquiries`	odczyt	zapytania z widgetu rezerwacyjnego czekające na odpowiedź
`list_booking_widgets`	odczyt	widgety rezerwacyjne na Państwa stronach: co oferują, wygląd, dozwolone strony i kod do wklejenia
`create_reservation`, `update_reservation`	zapis	rezerwacja lub zmiana pobytu
`block_dates`	zapis	zablokowanie terminu apartamentu na czas remontu
`transfer_reservation`	zapis	przeniesienie pobytu do innego apartamentu
`resolve_collision`	zapis	rozwiązanie kolizji przez anulowanie jednego z dwóch nakładających się pobytów
`update_reservation_estate`	zapis	cena, koszt sprzątania lub kod do drzwi jednego obiektu w pobycie albo informacja, że po pobycie nikt nie sprząta
`add_guest`, `update_guest`	zapis	księga gości pobytu
`assign_cleaner`, `mark_cleaning_complete`	zapis	sprzątanie po pobycie
`send_checkin_link`	zapis	wysłanie gościowi e-mailem linku do zameldowania online, a przy włączonych SMS-ach także SMS-em
`add_note`	zapis	dopisanie notatki na osi czasu pobytu
`list_invoices`	odczyt	wszystkie faktury i faktury korygujące, z filtrami i sumą
`get_invoices`	odczyt	czy pobyt wymaga faktury, na jaką kwotę i co już wystawiono
`issue_invoice`	zapis	wystawienie faktury za pobyt na głównego gościa, z numerem i ostatecznie
`send_invoice`	zapis	wysłanie faktury gościowi e-mailem z PDF w załączniku
`accept_inquiry`, `decline_inquiry`	zapis	przyjęcie zapytania ze strony (pobyt zostaje potwierdzony, a gość dostaje potwierdzenie) albo jego odrzucenie, zwolnienie terminu i powiadomienie gościa e-mailem
`create_estate`, `update_season`, `create_pin_code`	zarządzanie	zmiany obiektów (nowy obiekt wymaga pojemności `beds` i `extra_beds`), sezonów i kodów do drzwi, w tym listy sprzątania podzielonej na pokoje (`cleaning_checklist`); `update_estate` może też wyłączyć obiekt, aby nie był już oferowany ani wliczany do obłożenia; nowy lub ponownie włączony obiekt ponad limit planu Norka odrzuci
`set_season_price`, `create_rate_rule`, `update_rate_rule`	zarządzanie	cena obiektu w danym sezonie oraz cena stała lub rabat na konkretne terminy
`create_booking_widget`, `update_booking_widget`	zarządzanie	utworzenie lub zmiana widgetu rezerwacyjnego: oferowane obiekty, dozwolone strony, minimalna liczba nocy, pokazywanie cen i opinii, wyłączenie, kolory jako kod hex (`accent`, `free`, `busy`), zaokrąglenie i rozmiar (`compact`, `regular`, `large`); usunięcie widgetu i odnowienie jego tokenu pozostają w aplikacji

Każda odpowiedź zawiera link do strony w aplikacji, z której pochodzi, więc można ją sprawdzić.

Czego asystent celowo nie potrafi

Niczego nie usuwa. Ani rezerwacji, ani obiektów, gości czy członków zespołu.
Nie anuluje faktur. Anulowanie lub fakturę korygującą tworzą Państwo sami w aplikacji.
Nie tworzy ani nie unieważnia tokenów, więc wykradziony token nie może sam się odnowić.
Nie zarządza członkami i nie usuwa przestrzeni roboczej. Do tego potrzebna jest zalogowana sesja w aplikacji.
Nie widzi danych kontaktowych gości, chyba że zostanie zapytany o jednego konkretnego gościa po nazwisku; listy zawierają tylko imiona i nazwiska.
Nie wymknie się spod kontroli. Każde narzędzie ma limit wywołań; asystent, który utknie w pętli, dostaje czytelny błąd i niczego nie psuje.

Częste pytania

Czy można mieć kilka tokenów? Tak. Jeden token na klienta to dobry nawyk, bo każdy można wtedy unieważnić osobno.

Czy token działa poza MCP? Tak, REST API przyjmuje ten sam token. Zakres działa tak samo: token do odczytu zostanie odrzucony przy każdym żądaniu, które coś zmienia.

Chcę wypróbować serwer bez asystenta. Można użyć oficjalnego MCP Inspector: npx @modelcontextprotocol/inspector, a następnie podać adres serwera i nagłówek z tokenem.