Przejdź do głównej treści
Polski— Wybierz język
Menu

server_url i server_label

Lekcja 4 z 12 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Dwa parametry, bez których się nie obejdziesz
  2. server_url: Dokładny adres punktu końcowego
  3. server_label: Tożsamość serwera w rozmowie
  4. Minimalna konfiguracja w obu SDK
  5. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. na podstawie strony Remote MCP Tools od xAI: server_label dodaje prefiks do wywołań narzędzi, ale dokumentacja nie precyzuje dokładnego formatu tego prefiksu; notacja label__narzędzie używana w tym kursie jest konwencją czytelniczą – zweryfikuj rzeczywisty format w odpowiedziach swojego API. Źródło: Remote MCP Tools.

Dwa parametry, bez których się nie obejdziesz

Każde połączenie między Grok a zdalnym serwerem MCP opiera się na dwóch parametrach: server_url i server_label. Są one nie do negocjacji – bez nich API odrzuci żądanie, zanim cokolwiek spróbuje zrobić. Wszystkie inne parametry, z którymi spotkasz się później, jedynie doprecyzowują tę podstawę; nigdy jej nie zastępują.

server_url
Gdzie znajduje się serwer
server_label
Jak zidentyfikować serwer

server_url: Dokładny adres punktu końcowego

Parametr server_url zawiera pełny adres URL serwera MCP, do którego musi połączyć się Grok, a adres ten podlega ścisłym regułom.

Pierwsza z nich to HTTPS. Adres URL musi zaczynać się od https://, a xAI odrzuca każde nieszyfrowane połączenie HTTP. Powód jest prosty: wymiana danych między Grok a serwerem MCP obejmuje żądania Twoich użytkowników, wyniki działania narzędzi, a czasem nawet sam token uwierzytelniający. Pozwolenie, by krążyły one jako zwykły tekst, byłoby nie do obronienia.

# Poprawnie
mcp(server_url="https://mcp.deepwiki.com/mcp")

# Odrzucone przez API
mcp(server_url="http://mcp.deepwiki.com/mcp")

Druga reguła dotyczy precyzji ścieżki. Adres URL musi wskazywać bezpośrednio na punkt końcowy MCP, a nie na główną domenę. Prawie wszystkie serwery udostępniają swój punkt końcowy na dedykowanej ścieżce, przy czym konwencja ta różni się w zależności od serwera. Oto trzy poprawne formy, z którymi się spotkasz:

https://mcp.deepwiki.com/mcp
https://api.example.com/mcp
https://tools.monentreprise.com/v1/mcp

Trzecia reguła wynika z dwóch poprzednich: adresy localhost i prywatne adresy IP są wykluczone. Serwer musi być osiągalny z infrastruktury xAI, pod publiczną domeną i z ważnym certyfikatem SSL. Stawia to konkretne wyzwanie podczas rozwoju, ponieważ serwer MCP, który piszesz, działa na Twojej maszynie. Zwykłym rozwiązaniem jest użycie tunelu – na przykład ngrok lub Cloudflare Tunnel – który wystawia Twoją lokalną instancję za publicznym adresem HTTPS na czas testów.

server_label: Tożsamość serwera w rozmowie

server_label to krótki identyfikator, którego Grok używa do dodawania prefiksu do wywołań narzędzi pochodzących z tego serwera. Pełni on podwójną rolę: zapewnia czytelność śladów działania i usuwa wszelkie niejednoznaczności, gdy współistnieje wiele serwerów.

Dokumentacja xAI stwierdza, że etykieta dodaje prefiks do wywołań narzędzi z tego serwera, nie precyzując jednak dokładnego formatu tego prefiksu. W tym kursie oznaczamy narzędzie search_docs z serwera deepwiki jako deepwiki__search_docs dla lepszej czytelności: przed zbudowaniem logiki na tej podstawie zweryfikuj rzeczywisty format w odpowiedziach API.

mcp(
    server_url="https://mcp.deepwiki.com/mcp",
    server_label="deepwiki"
)
# Wywołania narzędzi z tego serwera będą miały prefiks "deepwiki"

Wybór dobrej etykiety kieruje się trzema kryteriami. Musi być krótka, ponieważ dodawana jest do nazwy każdego wywołania, a rozwlekła etykieta niepotrzebnie rozdmuchuje logi. Musi być opisowa, aby źródło wywołania było czytelne na pierwszy rzut oka bez konieczności konsultowania konfiguracji. Musi być unikalna w Twojej konfiguracji, w przeciwnym razie nie będziesz w stanie odróżnić dwóch serwerów od siebie. Poniższe przykłady spełniają te trzy wymagania:

server_label="deepwiki"     # Dokumentacja GitHub
server_label="crm"          # System zarządzania klientami
server_label="jira"         # Śledzenie zgłoszeń
server_label="search"       # Wewnętrzna wyszukiwarka

Sprawa staje się znacznie bardziej namacalna, gdy podłączysz wiele serwerów do tej samej sesji. Załóżmy, że zarówno Twoja wewnętrzna dokumentacja, jak i DeepWiki udostępniają narzędzie o nazwie search. Bez odrębnych etykiet nazwy narzędzi kolidują ze sobą i Grok nie ma sposobu, by wiedzieć, którego użyć. Dzięki etykietom oba narzędzia otrzymują różne prefiksy – tutaj oznaczone jako deepwiki__search i internal-docs__search – a zamieszanie znika. Wrócisz do tego punktu w lekcji poświęconej wielu serwerom.

Minimalna konfiguracja w obu SDK

Te dwa parametry wystarczą, aby uruchomić publiczny serwer MCP. W natywnym SDK xAI wygląda to tak:

from xai_sdk.tools import mcp

tools = [
    mcp(
        server_url="https://mcp.deepwiki.com/mcp",
        server_label="deepwiki"
    )
]

A oto dokładny odpowiednik w API Responses w formacie OpenAI:

tools = [{
    "type": "mcp",
    "server_url": "https://mcp.deepwiki.com/mcp",
    "server_label": "deepwiki",
}]

Kluczowe wnioski

  • server_url i server_label to jedyne dwa wymagane parametry
  • Adres URL musi używać HTTPS z ważnym certyfikatem SSL; localhost jest niedozwolony
  • Etykieta dodaje prefiks do wszystkich wywołań narzędzi z tego serwera (dokładny format nie jest udokumentowany; w tym kursie zapisujemy go jako etykieta__narzędzie)
  • Wybieraj etykiety krótkie, opisowe i unikalne dla każdego serwera
  • Etykieta jest kluczowa przy pracy z wieloma serwerami, aby uniknąć konfliktów nazw