Jak połączyć asystenta AI z DockAccess przez MCP

DockAccess udostępnia serwer MCP (Model Context Protocol). Dzięki niemu asystent AI, np. Claude Code, OpenAI Codex CLI czy Gemini CLI, może pracować na Twoim koncie DockAccess w Twoim imieniu. Sprawdzi limity planu, wypisze strony i ich usługi, uruchomi audyt automatyczny, pokaże wyniki audytów, subskrypcje i faktury.

Asystent widzi wyłącznie Twoją firmę i tylko te narzędzia, które zaznaczysz przy tworzeniu klucza.

Najważniejsze w skrócie

• Adres serwera: https://dockaccess.org/mcp
• Transport: Streamable HTTP (JSON-RPC 2.0, zwykłe odpowiedzi JSON, bez SSE i bez sesji)
• Logowanie: nagłówek Authorization: Bearer <klucz MCP>. Klucz zaczyna się od dockaccess_mcp_.
• Gdzie wygenerować klucz: Moje konto → Dostęp MCP (https://dockaccess.org/pl/moje-konto/mcp/)
• Kto może wygenerować klucz: osoba z rolą Właściciel, Administrator lub Developer w firmie
• Obsługiwane wersje protokołu MCP: 2025-11-25, 2025-06-18, 2025-03-26
• Zakres: jedna firma (ta, w której wygenerowano klucz), wybrane narzędzia, te same limity planu co w panelu

Krok 1. Wygeneruj klucz MCP

1. Zaloguj się na dockaccess.org i wybierz firmę, z którą asystent ma pracować. Klucz jest przypisany do firmy aktywnej w chwili jego utworzenia.
2. Otwórz Moje konto → Dostęp MCP.
3. Wpisz nazwę klucza, np. „Claude Code na laptopie”. Po nazwie rozpoznasz klucz na liście.
4. Ustaw ważność w dniach, od 1 do 365. Po tym czasie klucz przestaje działać.
5. Zaznacz dozwolone narzędzia. Narzędzia oznaczone jako „zapis” zmieniają dane, np. dodają stronę albo uruchamiają audyt. Zaznacz tylko to, czego asystent naprawdę potrzebuje.
6. Kliknij Wygeneruj klucz i od razu skopiuj sekret. Sekret pokazujemy tylko raz. DockAccess przechowuje wyłącznie jego skrót, więc nie da się go odzyskać, a jedynie wygenerować nowy klucz.

Po utworzeniu klucza na adres właściciela klucza przychodzi e-mail z powiadomieniem. Wiadomość nigdy nie zawiera sekretu. Jeśli to nie Ty tworzyłeś klucz, od razu go unieważnij.

Krok 2. Dodaj serwer do swojego klienta MCP

We wszystkich przykładach zamień YOUR_MCP_KEY na skopiowany sekret.

Claude Code

claude mcp add --transport http dockaccess https://dockaccess.org/mcp --header "Authorization: Bearer YOUR_MCP_KEY"
Skopiuj tekst

OpenAI Codex CLI

Codex czyta sekret ze zmiennej środowiskowej, więc nie trafia on do pliku konfiguracyjnego:

export DOCKACCESS_MCP_KEY=YOUR_MCP_KEY
codex mcp add dockaccess --url https://dockaccess.org/mcp --bearer-token-env-var DOCKACCESS_MCP_KEY
Skopiuj tekst

Gemini CLI

gemini mcp add --transport http --header "Authorization: Bearer YOUR_MCP_KEY" dockaccess https://dockaccess.org/mcp
Skopiuj tekst

Inne klienty (plik konfiguracyjny JSON)

Klienty, które obsługują zdalne serwery HTTP z własnymi nagłówkami, konfiguruje się zwykle tak:

{
  "mcpServers": {
    "dockaccess": {
      "type": "http",
      "url": "https://dockaccess.org/mcp",
      "headers": { "Authorization": "Bearer YOUR_MCP_KEY" }
    }
  }
}
Skopiuj tekst

Szczegóły, takie jak nazwa pliku i to, czy pole nazywa się type, transport czy url, zależą od klienta. Sprawdź jego dokumentację pod hasłem „remote MCP server” lub „Streamable HTTP”.

Czego nie da się podłączyć

Serwer DockAccess loguje wyłącznie kluczem w nagłówku Authorization, bez OAuth. Klienty, które przy zdalnych serwerach obsługują tylko logowanie OAuth i nie pozwalają dodać własnego nagłówka, nie połączą się bezpośrednio. Tak działają niektóre konektory w aplikacjach webowych czatów AI. W takim przypadku użyj klienta z wiersza poleceń (Claude Code, Codex CLI, Gemini CLI) albo edytora kodu, który pozwala ustawić nagłówek.

Krok 3. Sprawdź połączenie

Poproś asystenta np. o: „Pokaż limity mojego planu w DockAccess”. Asystent powinien wywołać narzędzie limits_get i zwrócić m.in. liczbę wyświetleń widżetu w tym miesiącu oraz audyty wykorzystane dzisiaj.

Jeśli asystent nie widzi żadnego narzędzia z DockAccess, przejdź do sekcji „Rozwiązywanie problemów”.

Dostępne narzędzia

Asystent widzi część wspólną dwóch zbiorów: narzędzi zaznaczonych w kluczu i narzędzi, do których masz uprawnienia w firmie. Jeśli ktoś odbierze Ci uprawnienie, narzędzie znika z klucza od razu, bez generowania nowego.

Konto i limity

• account_get (odczyt): dane Twojej firmy w DockAccess, czyli nazwa, dane do faktur, waluta i liczba aktywnych subskrypcji.
• limits_get (odczyt): limity planu i bieżące zużycie: wyświetlenia widżetu w tym miesiącu, liczba stron korzystających z każdej usługi, audyty automatyczne wykorzystane dzisiaj.

Strony (tokeny widżetu)

• sites_list (odczyt): strony firmy z domenami i włączonymi usługami. Argumenty opcjonalne: search (tekst), page (numer strony wyników, od 1).
• sites_get (odczyt): jedna strona: domeny, usługi (widżet, generator ALT, monitoring) i ich stan. Argument wymagany: site, czyli token strony z pola token w wyniku sites_list.
• sites_create (zapis): dodaje stronę. Argument wymagany: domains, lista domen, np. ["example.com"]. Opcjonalne: widget, alt, monitoring (prawda/fałsz). Usługa ponad limit planu zostaje utworzona jako wyłączona, a wynik mówi, która i dlaczego.
• sites_set_service (zapis): włącza lub wyłącza usługę strony. Argumenty wymagane: site, service (widget, alt lub monitoring), enabled (prawda/fałsz). Włączenie ponad limit planu zostanie odrzucone z podaniem powodu.

Audyty automatyczne

• audits_list (odczyt): audytowane adresy strony z ostatnim wynikiem na komputer i telefon. Argument wymagany: site. Opcjonalne: search, page.
• audits_history (odczyt): wcześniejsze audyty jednego adresu. Argumenty wymagane: site oraz address (address_uuid z wyniku audits_list). Opcjonalny: page.
• audits_scan (zapis): uruchamia audyt automatyczny podstrony. Argumenty wymagane: site oraz url: pełny adres w domenie strony, sama domena albo ścieżka, np. /kontakt. Opcjonalny: lang (pl lub en, język raportu, domyślnie en). Audyt wlicza się do dziennego limitu audytów. Narzędzie zwraca identyfikator audytu, a wynik pojawia się po kilku minutach i można go sprawdzić przez audits_list.

Subskrypcje i faktury

• subscriptions_list (odczyt): subskrypcje firmy: plan, status, okres, cena, następna płatność.
• subscriptions_get (odczyt): szczegóły jednej subskrypcji. Argument wymagany: subscription (identyfikator subskrypcji, UUID).
• invoices_list (odczyt): wystawione faktury firmy. Argument opcjonalny: page.

Kto widzi które narzędzia

Narzędzia zależą od roli w firmie:

• Właściciel i Administrator widzą wszystkie narzędzia klienta i mogą generować klucze.
• Developer może generować klucze i widzi narzędzia konta, stron i audytów. Nie widzi subskrypcji ani faktur.
• Tester, Księgowy i pozostałe role nie generują kluczy MCP.

Narzędzia z zapisem i bezpieczne ponawianie

Każde narzędzie z zapisem (sites_create, sites_set_service, audits_scan) wymaga argumentu operation_id: unikalnego identyfikatora UUID, który generuje klient. Dzięki temu operacja wykona się dokładnie raz:

• ponowienie z tym samym operation_id i tymi samymi argumentami (np. po zerwanym połączeniu) nie powtarza operacji, tylko zwraca jej pierwszy wynik;
• ten sam operation_id z innymi argumentami zostanie odrzucony;
• nowa operacja potrzebuje nowego operation_id.

Asystenci AI generują ten identyfikator sami, bo jest opisany w schemacie narzędzia.

Limity i ograniczenia

• Limity planu są takie same jak w panelu, bo narzędzia korzystają z tych samych mechanizmów. MCP nie daje dostępu do niczego, czego nie da się zrobić w panelu.
• Dzienny limit audytów automatycznych obejmuje audyty uruchomione przez MCP. Gdy się wyczerpie, narzędzie zwraca wyjaśnienie zamiast błędu technicznego.
• Limity zapytań do serwera MCP:
  • 60 na minutę na klucz;
  • 180 na minutę na osobę (wszystkie jej klucze razem);
  • 120 na minutę z jednego adresu IP.

Bezpieczeństwo

• Jedna firma na klucz. Klucz działa tylko w firmie, w której został wygenerowany. Argumenty narzędzi nie mogą tego zmienić, a dane innej firmy są dla klucza „nie znalezione”.
• Tylko wybrane narzędzia. Klucz pozwala wyłącznie na narzędzia zaznaczone przy jego tworzeniu, dodatkowo ograniczone Twoimi bieżącymi uprawnieniami.
• Sekret przechowujemy jako skrót. Nikt w DockAccess nie zobaczy Twojego sekretu, a e-mail o nowym kluczu nigdy go nie zawiera.
• Brak dostępu z przeglądarki. Serwer odrzuca żądania wysłane ze stron internetowych innych domen, więc obca strona nie wywoła narzędzi Twoim kluczem.
• Ścisła walidacja argumentów. Nieznane pola, złe typy i wartości spoza listy są odrzucane.
• Dziennik zdarzeń. Każde wywołanie trafia do dziennika firmy jako zdarzenie MCP z nazwą narzędzia. Argumentów ani wyników nie zapisujemy.
• Unieważnianie. Klucz unieważnisz w Moje konto → Dostęp MCP przyciskiem „Unieważnij”. Asystent traci dostęp natychmiast.

Klucz przestaje działać także wtedy, gdy:

• minie jego ważność;
• konto właściciela klucza zostanie dezaktywowane albo nie ma potwierdzonego adresu e-mail;
• właściciel klucza przestanie należeć do firmy;
• firma przestanie być aktywna.

Traktuj klucz MCP jak hasło: nie wklejaj go do repozytorium, czatu ani zgłoszeń. Jeśli wyciekł, unieważnij go i wygeneruj nowy.

Przykłady poleceń dla asystenta

• „Jakie mam strony w DockAccess i które usługi są na nich włączone?”
• „Ile audytów automatycznych zostało mi na dziś?”
• „Uruchom audyt strony głównej example.com i strony /kontakt. Raport po polsku.”
• „Porównaj wynik dostępności mojej strony głównej z poprzednim audytem.”
• „Dodaj stronę sklep.example.com z widżetem i monitoringiem.”
• „Kiedy jest najbliższa płatność za moją subskrypcję i jaki to plan?”

Asystent wykonuje działania tylko na Twoją wyraźną prośbę. Przed narzędziami z zapisem większość klientów pyta o potwierdzenie.

Jak to działa technicznie (dla programistów)

Serwer przyjmuje żądania POST https://dockaccess.org/mcp z treścią JSON-RPC 2.0. Wersję protokołu klient podaje w initialize albo w nagłówku MCP-Protocol-Version. Powiadomienia, czyli metody notifications/* bez id, dostają odpowiedź 202.

Inicjalizacja:

curl -s https://dockaccess.org/mcp \
  -H "Authorization: Bearer YOUR_MCP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
Skopiuj tekst

Lista narzędzi dostępnych dla klucza:

curl -s https://dockaccess.org/mcp \
  -H "Authorization: Bearer YOUR_MCP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
Skopiuj tekst

Wywołanie narzędzia z zapisem (operation_id to nowy UUID):

curl -s https://dockaccess.org/mcp \
  -H "Authorization: Bearer YOUR_MCP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"audits_scan","arguments":{"site":"TOKEN_STRONY","url":"/kontakt","lang":"pl","operation_id":"6f1c2c1e-8a3b-4a52-9a0e-2f4b1d7c9e10"}}}'
Skopiuj tekst

Odpowiedź udanego wywołania zawiera wynik dwa razy:

• jako tekst JSON w result.content[0].text;
• jako obiekt w result.structuredContent.

Gdy narzędzie odmawia wykonania, np. po wyczerpaniu limitu albo bez wykupionej usługi, odpowiedź ma result.isError: true i tekst w formacie kod: zdanie, np. limit_exceeded: …. Pozostałe błędy zwracają jedno ogólne zdanie, bez szczegółów technicznych.