Podepnij cudzy serwer MCP pod platformę

mcp-server-adapter to sidecar dla serwera MCP, którego kodu nie kontrolujesz, na przykład serwera open source albo od dostawcy. Czyta listę narzędzi tego serwera, wystawia ją bramce jako manifest i przekazuje każde wywołanie z poświadczeniem użytkownika, który je wykonał. Jeden adapter obsługuje jeden cudzy serwer i jeden system.

Adapter nie zamienia API REST na narzędzia. Nie ma pliku konfiguracji opisującego endpointy. Jeśli twój system ma tylko API REST, napisz serwer z szablonu, zobacz Napisz serwer z szablonu.

Czego się spodziewać

• Działają tylko narzędzia sklasyfikowane jako READ_ONLY. Narzędzie zmieniające dane pozostaje ukryte, bo narzędzia cudzego serwera nie nazywają zasobu, do którego dałoby się zawęzić zapis. Portal akceptuje dla adaptera tylko ryzyko READ_ONLY i akcję read.
• Cudzy serwer dostaje poświadczenie wywołującego użytkownika, nigdy wspólne. Trzymaj go w sieci, którą z adapterem dzieli tylko on.
• Narzędzia, których schematu wejścia nie da się ograniczyć, są pomijane: otwarte mapy, unie dwóch typów, rekurencja, listy bez items, głębokość powyżej 8. Powód podaje wpis logu event=foreign_tool_skipped.
• Każdy błąd cudzego serwera dociera do modelu jako not_found_or_denied, poza credential_required (HTTP 401) i upstream_unavailable. Błąd zwrócony przez serwer jako zwykły tekst dociera do modelu bez zmian, więc sprawdź, jak serwer zgłasza błędy.
• Lista narzędzi jest czytana przy starcie. Po zmianie zrestartuj adapter. Bramka pobiera nowy manifest w ciągu minuty, a zmienione narzędzia znów czekają na zatwierdzenie.
• Adapter nie ma polityk ani mapowania zakresów. Dostęp daje grupa mcp-<system>-read.

Zainstaluj adapter

Potrzebujesz Docker Engine z Compose v2.20 lub nowszym i 1 GiB pamięci. Platforma musi dosięgnąć tego hosta na porcie 8443, a ten host musi dosięgnąć https://<platform> na porcie 443.

1. W deploy/mcp-adapter.env uzupełnij cztery wymagane wartości:

   MCP_SERVER_ID=mcp-<system>
   MCP_GATEWAY_JWKS_URI=https://<platform>/.well-known/mcp-jwks.json
   MCP_CONNECT_URL=https://<platform>/connections?system={system}
   MCP_FOREIGN_URL=https://<cudzy serwer>

   <system> to identyfikator, który system ma w brokerze: od 2 do 31 małych liter i cyfr, zaczynający się od litery.

2. Jeśli cudzy serwer nie jest w domyślnej sieci Dockera, dodaj jego sieć pod mcp-adapter i pod networks: w compose.yaml. Żaden inny serwer nie może go dosięgnąć.

3. Uruchom adapter:

   docker compose up -d

   Adapter czeka do 90 sekund, aż cudzy serwer odpowie na tools/list, i kończy działanie, gdy nie odpowie.

4. Odczytaj odcisk certyfikatu:

   docker compose logs mcp-adapter | grep event=tls_certificate

   Oczekiwany wynik: event=tls_certificate source=generated fingerprint=sha256:...

5. Przekaż administratorowi platformy adres https://<ten host>:8443/mcp i odcisk. Dodaje on system i serwer, zobacz Serwery i Systemy. Dla produktu, który przyjmuje własny token użytkownika, system używa adaptera brokera generic-rest, typu user-secret, schematu Bearer.

Adapter generuje certyfikat przy pierwszym starcie i trzyma go w wolumenie state. Nowy wolumen to nowy odcisk i nowe zatwierdzenie; docker compose down -v go usuwa.

Ustawienia

Zmienna	Wymagana	Opis
MCP_SERVER_ID	tak	mcp-<system>
MCP_GATEWAY_JWKS_URI	tak	Zestaw kluczy bramki
MCP_CONNECT_URL	tak	Strona portalu, na której użytkownik łączy konto
MCP_FOREIGN_URL	tak	Adres cudzego serwera, https
MCP_FOREIGN_PATH	nie	Ścieżka MCP serwera, domyślnie /mcp
MCP_FOREIGN_AUTHORIZATION_FORMAT	nie	Jak poświadczenie staje się nagłówkiem. Domyślnie Token {credential}; {credential} musi wystąpić dokładnie raz
MCP_FOREIGN_DISCOVERY_AUTHORIZATION	nie	Nagłówek dla tools/list przy starcie, dla serwerów odrzucających żądanie bez niego
MCP_ADAPTER_TOOLS_INCLUDE	nie	Narzędzia do opublikowania, po przecinku. Puste oznacza wszystkie, które da się ograniczyć
MCP_ADAPTER_STRIP_PREFIX	nie	Prefiks do usunięcia z nazw narzędzi

Własny certyfikat, Redis dla wielu instancji i limity są w tym samym pliku oraz w src/main/resources/application.yml.

Przykład: mcp-atlassian przed Jirą

Przykład z repozytorium stawia sooperset/mcp-atlassian 0.23.1 (MIT) przed Jirą z czterema narzędziami odczytu. Działa na stosie testowym: cudzy serwer mówi zwykłym http, co adapter przyjmuje tylko w profilu devstack. Wszystkie ustawienia są w deploy/docker-compose.demo.yml.

1. Pobierz obraz, przypięty skrótem:

   docker pull ghcr.io/sooperset/mcp-atlassian@sha256:5b7c9b64d4eb3210cab74be8bf3e6aeea9ed14f3042dc59ba5c5287bd4dbe466

2. Włącz deploy/docker-compose.demo.yml do swojego stosu testowego i ustaw ADAPTER_IMAGE oraz MCP_GATEWAY_JWKS_URI. Jeśli stos uruchamia już natywny mcp-jira, zatrzymaj go: adapter zajmuje jego identyfikator serwera.

3. Zachowaj te ustawienia cudzego serwera:

   ENABLED_TOOLS: jira_get_issue,jira_search,jira_get_all_projects,jira_get_transitions
   JIRA_PERSONAL_TOKEN: placeholder-never-used
   ALLOW_GLOBAL_CRED_FALLBACK: "false"

   ENABLED_TOOLS wymienia wyłącznie narzędzia odczytu. Token to wypełniacz: bez niego serwer nie wystawia narzędzi Jiry. Przy wyłączonym fallbacku wywołanie bez poświadczenia kończy się 401.

4. Zachowaj te ustawienia adaptera:

   MCP_FOREIGN_URL: http://mcp-atlassian:8000
   MCP_FOREIGN_ALLOW_PLAIN_HTTP: "true"
   MCP_FOREIGN_AUTHORIZATION_FORMAT: "Token {credential}"
   MCP_FOREIGN_DISCOVERY_AUTHORIZATION: "Token discovery-only"
   MCP_ADAPTER_STRIP_PREFIX: jira_

5. Uruchom stos komendą docker compose up -d.

6. W portalu dodaj serwer http://mcp-jira.internal:8443/mcp z opcją “allow plain http”, zatwierdź połączenie i zatwierdź cztery narzędzia: get_issue, search, get_all_projects i get_transitions.

Kontener cudzego serwera jest w stosie najmniej zaufany. Fragment uruchamia go w trybie tylko do odczytu, bez uprawnień (capabilities) i z limitami pamięci, w dwóch sieciach wewnętrznych (jedna wspólna z adapterem, druga z Jirą).

Typowe problemy

Objaw	Przyczyna	Rozwiązanie
Adapter kończy działanie zaraz po starcie	Cudzy serwer nie odpowiedział na tools/list w 90 s albo odrzuca żądania bez Authorization	Sprawdź MCP_FOREIGN_URL i sieć; w drugim przypadku ustaw MCP_FOREIGN_DISCOVERY_AUTHORIZATION
Status serwera certificate_changed	Wolumen state odtworzono	Zatwierdź nowy odcisk w portalu
Brakuje narzędzia na liście	Nie jest zatwierdzone, nie jest READ_ONLY albo nie da się ograniczyć jego schematu	Sprawdź w logu event=foreign_tool_skipped
Narzędzie zmieniło się po nowym obrazie cudzego serwera	Lista narzędzi jest czytana przy starcie	Zrestartuj adapter; zmienione narzędzia znów czekają na zatwierdzenie