Instalacja lokalna

Ta instalacja służy do testów. Platforma i serwer MCP działają jako dwa projekty Compose na jednym komputerze. Kroki poniżej używają serwera GitLab, inny serwer instaluje się tak samo (Instalacja serwera MCP). Przebieg sprawdzono na macOS z Docker Desktop. Na Windows wykonuj polecenia w Git Bash.

Zasady dla nazwy lokalnej

• Jako nazwę platformy użyj mcp.localhost, nie localhost. W kontenerze serwera localhost oznacza sam kontener, a nginx odrzuca nazwę TLS inną niż MCP_DOMAIN. Przeglądarki i Node kierują *.localhost na adres pętli zwrotnej.
• Certyfikat musi mieć subjectAltName=DNS:mcp.localhost. Wystaw go własnym CA.
• Przykłady publikują platformę na porcie 21443 (http 21080) pod adresem 127.0.0.1, żeby nie kolidować z innym stosem na 443.
• Kontener serwera trafia do platformy przez extra_hosts, a gateway do serwera przez host.docker.internal.

Potrzebujesz Docker Desktop, openssl i keytool (z dowolnego JDK).

1. Utwórz CA i certyfikat

1. Utwórz CA i certyfikat dla mcp.localhost:

   mkdir -p ~/mcp-local/ca
   cd ~/mcp-local/ca
   openssl req -x509 -newkey rsa:3072 -nodes -days 365 -keyout ca.key -out ca.crt -subj "/CN=MCP local CA" \
     -addext "basicConstraints=critical,CA:TRUE" -addext "keyUsage=critical,keyCertSign,cRLSign"
   openssl req -newkey rsa:2048 -nodes -keyout tls.key -out tls.csr -subj "/CN=mcp.localhost"
   printf 'subjectAltName=DNS:mcp.localhost\nbasicConstraints=CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\n' > ext.cnf
   openssl x509 -req -in tls.csr -CA ca.crt -CAkey ca.key -CAcreateserial -days 365 -extfile ext.cnf -out tls.crt

2. Dodaj ca.crt do zaufanych w systemie, żeby przeglądarka mu ufała. Na macOS:

   sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/mcp-local/ca/ca.crt

   Na Windows, w PowerShell jako administrator:

   certutil -addstore -f Root $HOME\mcp-local\ca\ca.crt

3. Jeśli system, z którym się łączysz (na przykład GitLab), używa certyfikatu z firmowego CA, zapisz certyfikat tego CA jako ~/mcp-local/ca/company-ca.crt. Potrzebują go i broker, i serwer.

2. Uruchom platformę

1. Pobierz pakiet i wejdź do niego:

   mkdir -p ~/mcp-local
   cd ~/mcp-local
   git clone https://github.com/aiwcorpo/mcp-platform.git platform
   cd platform

2. Skopiuj certyfikat i CA. certs/company-ca.crt ma zawierać lokalne CA, a po nim firmowe CA, jeśli je masz:

   cp ../ca/tls.crt ../ca/tls.key certs/
   cat ../ca/ca.crt > certs/company-ca.crt

   Jeśli zapisałeś firmowe CA, dopisz je: cat ../ca/company-ca.crt >> certs/company-ca.crt.

3. Zapisz .env. Każda linia to osobne polecenie:

   grep -v '^MCP_DOMAIN=' platform.env > .env
   echo COMPOSE_PROJECT_NAME=mcp-local >> .env
   echo MCP_DOMAIN=mcp.localhost >> .env
   echo MCP_BIND=127.0.0.1 >> .env
   echo MCP_HTTPS_PORT=21443 >> .env
   echo MCP_HTTP_PORT=21080 >> .env
   echo MCP_PUBLIC_ORIGIN=https://mcp.localhost:21443 >> .env

   COMPOSE_PROJECT_NAME daje projektowi własne wolumeny i sieci, więc drugi projekt o nazwie mcp-platform na tym komputerze zostaje nietknięty.

4. Uruchom:

   docker compose up -d
   docker compose ps

   Po 3 do 5 minutach wszystkie usługi są zdrowe.

5. Wypisz hasło początkowe mcp-admin:

   docker compose run --rm init show admin-password

6. Otwórz https://mcp.localhost:21443/auth/realms/mcp/account, zaloguj się jako mcp-admin, ustaw nowe hasło i OTP. Portal jest pod https://mcp.localhost:21443/.

Jeśli zmienisz company-ca.crt po pierwszym starcie, uruchom docker compose up -d, potem docker compose logs init | grep warn. Log poda polecenie docker compose restart ... do wykonania.

3. Uruchom serwer MCP

1. Pobierz katalog deploy/ serwera:

   cd ~/mcp-local
   git clone https://github.com/aiwcorpo/mcp-server-gitlab.git server-gitlab
   cd server-gitlab/deploy

2. Zwiąż serwer z adresem pętli zwrotnej i spraw, żeby nazwa platformy działała w jego kontenerze:

   echo MCP_GITLAB_BIND=127.0.0.1 > .env
   printf 'services:\n  mcp-gitlab:\n    extra_hosts: ["mcp.localhost:host-gateway"]\n' > compose.override.yaml

3. Utwórz magazyn zaufania serwera. Potrzebuje lokalnego CA (do pobrania kluczy gatewaya) i firmowego CA, jeśli GitLab go używa:

   keytool -importcert -noprompt -alias mcp-local -file ~/mcp-local/ca/ca.crt -keystore certs/truststore.p12 -storetype PKCS12 -storepass changeit
   keytool -importcert -noprompt -alias company-ca -file ~/mcp-local/ca/company-ca.crt -keystore certs/truststore.p12 -storetype PKCS12 -storepass changeit
   chmod 644 certs/truststore.p12

   Pomiń drugie polecenie, jeśli nie masz firmowego CA.

4. Otwórz mcp-gitlab.env i ustaw te wartości. Odkomentuj linię JAVA_TOOL_OPTIONS:

   MCP_GATEWAY_JWKS_URI=https://mcp.localhost:21443/.well-known/mcp-jwks.json
   MCP_CONNECT_URL=https://mcp.localhost:21443/connections?system={system}
   MCP_GITLAB_URL=https://<gitlab>

5. Uruchom serwer i odczytaj odcisk jego certyfikatu:

   docker compose up -d
   docker compose logs mcp-gitlab | grep event=tls_certificate

   Zachowaj odcisk do zatwierdzenia w portalu. Komputer musi widzieć GitLaba (sieć firmowa lub VPN), bo łączą się z nim i serwer, i broker.

4. Dodaj serwer w portalu

Zaloguj się do portalu jako mcp-admin i wykonaj kroki z Serwery i Systemy. Użyj tych wartości:

Gdzie	Wartość
Adres serwera	https://host.docker.internal:8443/mcp
Zaufanie	Certyfikat jest samopodpisany, więc połączenie jest przypięte. Porównaj odcisk z tym z kroku 3.5.
Konsola Keycloaka	https://mcp.localhost:21443/auth/admin/mcp/console/

5. Połącz Claude Code

Claude Code musi ufać lokalnemu CA i używać lokalnego adresu:

export NODE_EXTRA_CA_CERTS=$HOME/mcp-local/ca/ca.crt

W tej samej powłoce uruchom polecenie claude mcp add ze strony portalu z adresem MCP. Adres to https://mcp.localhost:21443/mcp. Zobacz Claude Code.

Linux

Na Linuksie host.docker.internal nie jest zdefiniowane. Utwórz compose.override.yaml w katalogu platformy:

services:
  gateway:
    extra_hosts: ["host.docker.internal:host-gateway"]

Usuń wszystko

cd ~/mcp-local/server-gitlab/deploy
docker compose down -v
cd ~/mcp-local/platform
docker compose down -v

down -v usuwa wolumeny tylko tych dwóch projektów. Na koniec usuń lokalne CA z magazynu certyfikatów systemu.