Jak dodać i zarządzać systemami

System to dane brokera poświadczeń: adres produktu i sposób, w jaki broker zdobywa do niego poświadczenie. Serwer MCP to osobny program z narzędziami, a jego manifest wskazuje system, którego używa. Bez systemu użytkownicy nie mają czego połączyć, a wywołania narzędzi kończą się błędem. Dodaj system przed zatwierdzeniem serwera (zobacz Jak dodać i zatwierdzić serwer MCP).

Wszystko na tej stronie robisz w portalu: Administracja, Systemy. Potrzebujesz grupy mcp-platform-admin. Broker podejmuje zmianę w ciągu 5 sekund, bez restartu.

Dodaj system

1. Otwórz Administracja, Systemy i wybierz Dodaj system.
2. Wpisz Identyfikator systemu: od 2 do 31 małych liter i cyfr, zaczynając od litery. Musi być taki sam jak system z manifestu serwera (na przykład jira). Nie można go później zmienić. Identyfikatory gateway, offboarding, portal, broker, prometheus, platform, admin, registry, adapter, internal i ci są zarezerwowane.
3. Opcjonalnie wpisz Nazwa wyświetlana (od 1 do 64 znaków). Strony administracji pokazują ją zamiast identyfikatora.
4. Wybierz Adapter (tabela poniżej).
5. Wpisz Adres bazowy produktu. Musi zaczynać się od https.
6. Wypełnij pola, których wymaga wybrany adapter (następne sekcje).
7. Wybierz Zapisz. Jeśli portal o to poprosi, potwierdź tożsamość u dostawcy tożsamości: zapis systemu wymaga świeżego MFA, a po powrocie formularz wraca. Sekret klienta nie jest po drodze zachowywany, więc wpisz go ponownie.

Wybierz adapter

Adapter decyduje, jak broker rozmawia z produktem, jakie typy poświadczeń są możliwe i jak sprawdzany jest token, który użytkownik zapisuje.

Adapter	Typy poświadczeń	Sprawdzenie zapisanego sekretu (whoami)
atlassian-dc (produkt jira albo confluence)	Token PAT (user-secret)	Jira: GET /rest/api/2/myself. Confluence: GET /rest/api/user/current
gitlab	Token PAT (user-secret), OAuth (user-oauth)	GET /api/v4/user
opensearch	Wymiana tokenu (token-exchange)	Brak. Broker wymienia token użytkownika u dostawcy tożsamości na odbiorcę (audience) systemu
generic-rest	Konto serwisowe (service-account) albo token PAT (user-secret), jedno z nich	GET <adres bazowy><ścieżka sprawdzenia>, gdy ustawisz Ścieżka sprawdzenia

Sprawdzenie działa w chwili, gdy użytkownik zapisuje token. Odpowiedź 2xx zapisuje go. 401 albo 403 odrzuca (secret_invalid). Każda inna odpowiedź to upstream_unavailable i nic nie jest zapisywane.

Pola

Pole	Kiedy się pojawia	Znaczenie
Produkt	atlassian-dc	Jira albo Confluence. Decyduje o wywołaniu whoami
Typ poświadczenia tego systemu	generic-rest	Jeden wybór: Token PAT albo Konto serwisowe. Bez OAuth i bez mieszania
Ścieżka sprawdzenia (opcjonalna)	generic-rest z tokenem PAT	Ścieżka na adresie bazowym, zaczynająca się pojedynczym ukośnikiem, bez hosta, zapytania i .. (na przykład /api/me). Bez niej token jest zapisywany bez sprawdzenia, a połączenie nie pokazuje konta
Pole nazwy użytkownika w odpowiedzi	generic-rest z tokenem PAT	Pole odpowiedzi z nazwą użytkownika albo wskaźnik JSON, na przykład /user/login
Obsługiwane typy poświadczeń	pozostałe adaptery	Zaznacz typy, które system przyjmuje. Konta serwisowego nie można łączyć z typem użytkownika. Wymiany tokenu nie można łączyć z innymi typami
Typ domyślny	zawsze	Jeden z obsługiwanych typów
Schemat sekretu przekazywanego gatewayowi	zawsze	Bearer, Basic, Token albo ApiKey: jak poświadczenie trafia do nagłówka w stronę serwera
Schemat tokenu użytkownika	token PAT	Jak schemat powyżej, Bearer albo Basic. Przy Basic formularz połączenia prosi użytkownika o login obok tokenu (na przykład Jira Data Center z loginem i hasłem)
Odbiorca (audience) wymienianego tokenu	wymiana tokenu	Wymagany. Musi pasować do ustawienia brokera broker.token-exchange.allowed-audiences (dokładne wartości albo wzorce z *). Ustawienie jest domyślnie puste, a wtedy nie da się utworzyć systemu z wymianą tokenu
Adres unieważniania (opcjonalny)	zawsze	Adres https wywoływany, gdy użytkownik się rozłącza (OAuth)
Limit czasu wywołań (opcjonalny)	zawsze	Czas trwania ISO 8601 do 10 minut, na przykład PT30S
Identyfikator klienta, Sekret klienta, Adres tokenu, Zakresy OAuth (oddzielone spacjami)	OAuth lub wymiana tokenu	Klient OAuth, którego broker używa w produkcie. System z wymianą tokenu nie ma adresu tokenu: broker używa punktu tokenów swojego dostawcy tożsamości
Adres autoryzacji	OAuth	Adres, pod którym użytkownik loguje się do produktu

Wszystkie adresy to https. Zwykły http jest możliwy tylko z ustawieniem brokera allow-plain-http, przeznaczonym dla środowiska deweloperskiego.

Sekret klienta

Sekret klienta trafia do magazynu sekretów brokera (OpenBao) i nigdy nie jest pokazywany ponownie. Przy edycji systemu pole mówi Sekret jest zapisany. Zostaw puste, żeby go zachować. Zostaw je puste, aby zachować sekret, albo wpisz nowy, aby go zastąpić.

Zmiana adresu systemu

Jeśli zmienisz Adres bazowy, Adres unieważniania, Adres autoryzacji, Adres tokenu albo Identyfikator klienta, portal ostrzega: Zapis usunie połączenia wszystkich użytkowników z tym systemem i będą musieli połączyć się ponownie. Wypisuje też, co się zmieniło. Sekret klienta musisz wpisać ponownie.

Po zapisie każde połączenie z systemem dostaje stan needs_reconnect. Wiersz w Połączenia z systemami pokazuje Połącz ponownie i każdy użytkownik łączy konto od nowa. Do produktu nic nie jest wysyłane. Inne zmiany (zakresy, limit czasu, typ domyślny, nowy sekret) nie ruszają połączeń.

Usuń system

Usuń kasuje ustawienia, sekret klienta i połączenia wszystkich użytkowników z tym systemem. Do samego produktu nic nie jest wysyłane. Usunięcie wymaga świeżego MFA. Potem wywołania narzędzi tego systemu kończą się błędem system_not_configured.

Konta serwisowe

Konto serwisowe to jedno konto platformy w produkcie, wspólne dla wszystkich użytkowników systemu (na przykład service desk, w którym każde wywołanie używa tego samego użytkownika technicznego). Użytkownicy niczego nie łączą, a dostęp rozstrzygają wyłącznie grupy i mapowanie zakresów, więc nadaj kontu minimalne uprawnienia potrzebne narzędziom.

Konto serwisowe jest możliwe tylko z adapterem generic-rest i typem Konto serwisowe. Klucza nie wpisuje się w portalu. Operator zapisuje go w magazynie KV OpenBao, a broker go tylko czyta.

1. Dodaj system w portalu z adapterem generic-rest i typem Konto serwisowe.

2. Zapisz klucz w secret/mcp/service-accounts/<system>, gdzie <system> to identyfikator systemu. Użyj tokenu polityki OpenBao, która może tworzyć i aktualizować secret/data/mcp/service-accounts/*. Polityka samego brokera może ten wpis tylko czytać.

   Dla systemu ze schematem Bearer, Token albo ApiKey zapisz poświadczenie w takiej postaci, w jakiej trafia do nagłówka po nazwie schematu:

   bao kv put secret/mcp/service-accounts/<system> value=<token-konta-serwisowego>

   Dla systemu ze schematem Basic zapisz login i hasło. Broker sam zbuduje wartość nagłówka (login nie może zawierać dwukropka):

   bao kv put secret/mcp/service-accounts/<system> username=<login> password=<haslo>

3. Jeśli klucz jest rotowany według harmonogramu, dodaj datę wygaśnięcia w formacie RFC 3339, na przykład:

   bao kv put secret/mcp/service-accounts/<system> value=<token-konta-serwisowego> expires_at=2027-06-30T00:00:00Z

Każde bao kv put zapisuje nową wersję całego wpisu, więc powtórz każde pole, które ma zostać.

W pakiecie Compose

Pakiet nie przechowuje tokenu, który może zapisywać sekrety: token root jest unieważniany po pierwszym starcie, a polityka provisionera nie obejmuje żadnej ścieżki pod secret/. OpenBao 2.7 odrzuca też bao operator generate-root bez tokenu (od 2.6 komenda używa uwierzytelnionego endpointu /sys/generate-root-token), więc sam klucz odpieczętowania nie da nowego tokenu root.

Znane ograniczenie wersji 2.0

Pakiet Compose nie ma wspieranego sposobu zapisu secret/mcp/service-accounts/<system> po pierwszym starcie. Dopóki mcp-platform nie udostępni do tego polityki operatora, system z typem Konto serwisowe nie dostanie w pakiecie swojego klucza. Używaj tego typu poświadczenia z OpenBao, w którym masz token z polityką pozwalającą tworzyć i aktualizować secret/data/mcp/service-accounts/*.

Jak to działa:

• Broker nie przechowuje klucza w pamięci podręcznej. Rotacja w OpenBao działa od następnego wywołania, a własna pamięć podręczna gatewaya trzyma poświadczenie najwyżej 60 sekund.
• Przy ustawionym expires_at broker ogranicza pamięć podręczną do pozostałego czasu. Po tym czasie klucz uchodzi za wygasły.
• Brak wpisu, wpis bez użytecznego value (albo username i password), wartość, która nie jest poprawnym tokenem nagłówka (na przykład ze spacjami), expires_at, które nie jest znacznikiem czasu, i wygasły klucz kończą się odmową: broker odpowiada 503 upstream_unavailable i nic nie jest wysyłane do produktu.
• Polityka OpenBao brokera dla secret/data/mcp/service-accounts/* jest tylko do odczytu. Klucz nigdy nie trafia do przeglądarki, logów ani audytu.