Własny klient MCP (konfiguracja OAuth)

Ta strona jest dla deweloperów i organizacji, które chcą podłączyć własny klient MCP do serwera MCP Autosignly, zamiast korzystać z gotowej powłoki, takiej jak konektor w katalogu Claude czy Claude Code.

Serwer to standardowy zdalny endpoint MCP zabezpieczony OAuth 2.1. Twój klient loguje się jako użytkownik 16it i działa w jego imieniu, w zakresie wybranej firmy, zawsze na środowisku produkcyjnym.

• Endpoint MCP: https://mcp.16it.eu/mcp (Streamable HTTP, token Bearer)
• Serwer autoryzacji (Keycloak): https://auth.16it.eu/realms/prod-16it

Krok 1: poproś o klienta OAuth

Serwer nie pozwala na samodzielną (dynamiczną) rejestrację klientów, więc pierwszym krokiem jest poproszenie 16it o założenie klienta OAuth dla Twojej integracji. Napisz na [email protected] i podaj:

• Nazwę integracji i krótki opis, co robi.
• Typ klienta:
  • Public + PKCE dla aplikacji natywnej, desktopowej, mobilnej lub CLI (bez sekretu trzymanego na urządzeniu).
  • Confidential dla integracji po stronie serwera, która bezpiecznie przechowa sekret klienta.
• Redirect URI używane przez Twojego klienta po logowaniu. Pętla lokalna (http://localhost:<port>/...) jest w porządku dla aplikacji natywnych i CLI.
• Kontakt do przekazania poświadczeń.

Zakładamy klienta w realmie prod-16it i zwracamy:

• Twój client_id,
• client_secret (tylko klienci confidential, przekazywany bezpiecznym kanałem).

Krok 2: dane OAuth i discovery

Większość klientów MCP odkrywa wszystko z serwera. Na niezautoryzowane wywołanie endpoint odpowiada 401 z nagłówkiem WWW-Authenticate wskazującym na metadane zasobu, więc zgodny klient sam znajdzie serwer autoryzacji:

• Metadane zasobu chronionego (RFC 9728): https://mcp.16it.eu/.well-known/oauth-protected-resource
• Metadane serwera autoryzacji (RFC 8414): https://auth.16it.eu/realms/prod-16it/.well-known/openid-configuration

Jeśli Twój klient potrzebuje endpointów wprost:

Ustawienie	Wartość
Authorization endpoint	https://auth.16it.eu/realms/prod-16it/protocol/openid-connect/auth
Token endpoint	https://auth.16it.eu/realms/prod-16it/protocol/openid-connect/token
Scope'y	openid profile email (dodaj offline_access dla refresh tokenu)
Flow	Authorization Code. Klienci public muszą użyć PKCE (S256); klienci confidential uwierzytelniają się sekretem.
Resource / audience	Backend waliduje wystawcę (issuer) i podpis tokenu, a nie konkretny audience, więc parametr resource nie jest wymagany.

Krok 3: połączenie

1. Uruchom standardowy flow Authorization Code na powyższych endpointach ze swoim client_id (i PKCE dla klientów public). Użytkownik loguje się kontem 16it i zatwierdza.

2. Wymień kod na token dostępu w token endpoint (oraz refresh token, jeśli poprosiłeś o offline_access).

3. Wołaj endpoint MCP z tokenem:

   POST https://mcp.16it.eu/mcp
   Authorization: Bearer <token dostępu>
   Accept: application/json, text/event-stream
   Content-Type: application/json

   Zacznij od initialize, potem tools/list, potem tools/call. Narzędzia zależne od firmy przyjmują argument companyId, który odczytasz z autodocuments_list_my_companies.

4. Odświeżaj token dostępu refresh tokenem, zanim wygaśnie; nie ma osobnego klucza API do rotowania.

Działanie w imieniu Twoich użytkowników

Jeśli budujesz produkt obsługujący wielu użytkowników, uruchamiaj flow Authorization Code raz na każdego użytkownika końcowego. Każdy Twój użytkownik loguje się własnym kontem 16it, a Twoja aplikacja przechowuje jego refresh token. Konsekwencje:

• Nigdy nie otrzymujesz master-poświadczenia czytającego dane wszystkich tenantów. Każdy token jest ograniczony dokładnie do tego, do czego dany użytkownik 16it ma dostęp.
• Klient confidential (po stronie serwera) jest tu właściwym wyborem: trzymasz jeden client_id / sekret produktu i przez niego pozyskujesz osobny token per użytkownik.
• Używaj offline_access, żeby backend mógł działać w imieniu użytkownika między sesjami, i odświeżaj każdy token przed wygaśnięciem.

Co potrafi klient

Serwer udostępnia skupiony zestaw narzędzi, taki sam na każdej powłoce:

Odczyt

• Lista firm, do których należy użytkownik
• Lista i podgląd szablonów dokumentów wraz z ich etykietami (tagami)
• Lista i podgląd dokumentów (ze statusem podpisu) oraz ich załączników
• Wyszukiwanie kontrahentów (firm i osób), z którymi podpisuje użytkownik
• Sprawdzenie reguł podpisu per kraj i zasięgu SMS

Tworzenie / wysyłka

• Utworzenie szablonu dokumentu (z HTML)
• Wygenerowanie dokumentu z szablonu
• Porządkowanie pracy etykietami (tagami) i zarządzanie załącznikami dokumentu (lista, kolejność, usuwanie)
• Wysłanie dokumentu do podpisu (SES / AES / QES, zgodne z eIDAS)

Dane i uprawnienia

• Klient działa jako zalogowany użytkownik i może tylko to, co konto 16it tego użytkownika.
• Każda operacja zależna od firmy jest ograniczona do firmy przekazanej w wywołaniu.
• Serwer zawsze pracuje na produkcyjnym środowisku użytkownika i nigdy nie dosięgnie sandboxa.
• Odpowiedzi zwracają tylko pola wymienione w polityce prywatności; adresy e-mail i numery telefonu podpisujących nie są nigdy zwracane.

notatka

Każda integracja dostaje własnego klienta OAuth. Jeśli sekret kiedykolwiek wycieknie, poproś 16it o jego rotację; nie wpłynie to na inne integracje.