Kompletna konfiguracja serwera MCP
Na tej stronie
Łączymy wszystko w całość
Poznałeś już każdy parametr z osobna. Ta lekcja scala je w kompletne konfiguracje, dokładnie tak, jak będziesz je zapisywać w praktyce, pokazując za każdym razem odpowiedniki w obu głównych SDK. Celem nie jest wprowadzanie nowych koncepcji, lecz dostarczenie Ci wzorców, które możesz bezpośrednio adaptować.
Oto przegląd sześciu parametrów wraz z informacją, czy są wymagane, czy opcjonalne.
| Parametr | Wymagany | Rola |
|---|---|---|
server_url | Tak | Adres HTTPS serwera MCP |
server_label | Tak | Prefiks wywołania narzędzia |
server_description | Nie | Pomaga Grokowi w wyborze serwera |
allowed_tool_names | Nie | Ogranicza dostępne narzędzia |
authorization | Nie | Token uwierzytelniający |
headers | Nie | Dodatkowe nagłówki HTTP |
Najprostszy przypadek
Dwa parametry wystarczą, gdy serwer jest publiczny i nie wymaga uwierzytelnienia.
# xAI SDK
tools = [mcp(server_url="https://mcp.deepwiki.com/mcp", server_label="deepwiki")]
# Responses API (OpenAI)
tools = [{
"type": "mcp",
"server_url": "https://mcp.deepwiki.com/mcp",
"server_label": "deepwiki"
}]
Dokładnie tak zapiszesz konfigurację dla DeepWiki. Grok uzyskuje wtedy dostęp do wszystkich narzędzi serwera, co w tym przypadku jest akceptowalne, ponieważ jest to publiczna usługa tylko do odczytu. Gdy tylko serwer będzie należał do Twojej organizacji, taka konfiguracja stanie się niewystarczająca.
Wewnętrzny serwer tylko do odczytu
Podnieśmy poprzeczkę: przedsiębiorczy system CRM, z którego agent musi mieć możliwość pobierania danych, ale nigdy ich modyfikowania. Dodajemy trzy parametry, każdy z innego powodu – opis kieruje modelem, token potwierdża tożsamość, a lista dozwolonych narzędzi blokuje zapis.
# xAI SDK
tools = [
mcp(
server_url="https://api.monentreprise.com/mcp",
server_label="crm",
server_description="Wewnętrzny CRM. Tylko wyszukiwanie kontaktów i firm.",
authorization=f"Bearer {os.getenv('CRM_TOKEN')}",
allowed_tool_names=["search_contacts", "get_contact", "list_companies"]
)
]
# Responses API (OpenAI)
tools = [{
"type": "mcp",
"server_url": "https://api.monentreprise.com/mcp",
"server_label": "crm",
"server_description": "Wewnętrzny CRM. Tylko wyszukiwanie kontaktów i firm.",
"authorization": f"Bearer {os.getenv('CRM_TOKEN')}",
"allowed_tool_names": ["search_contacts", "get_contact", "list_companies"]
}]
Porównaj te dwa bloki: zawartość jest identyczna, zmienia się tylko opakowanie. Funkcja pomocnicza mcp() przyjmuje argumenty nazwane; format OpenAI oczekuje słownika z dodatkowym kluczem "type". To jedyna różnica, o której musisz pamiętać, tłumacząc konfigurację z jednego SDK na drugie.
Kompleksowa konfiguracja
Ostatni krok: połączenie wszystkich sześciu parametrów w rzeczywistym wywołaniu xAI SDK.
import os
from xai_sdk import Client
from xai_sdk.tools import mcp
client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
tools=[
mcp(
server_url="https://tools.monentreprise.com/v1/mcp",
server_label="outils-internes",
server_description="Platforma narzędzi wewnętrznych: zarządzanie dokumentami, zgłoszenia wsparcia, baza wiedzy. Dostęp tylko do odczytu.",
authorization=f"Bearer {os.getenv('TOOLS_MCP_TOKEN')}",
headers={
"X-Organization-Id": os.getenv("ORG_ID"),
"X-Environment": "production",
"X-Request-Source": "grok-agent"
},
allowed_tool_names=[
"search_documents",
"get_document",
"search_tickets",
"get_ticket",
"search_knowledge_base"
]
)
],
include=["verbose_streaming"],
)
Zwróć uwagę na wewnętrzną spójność tego przykładu. Opis zapowiada dostęp tylko do odczytu, a pięć dozwolonych narzędzi to wyłącznie operacje wyszukiwania – nie ma sprzeczności między tym, co model sądzi, że może zrobić, a tym, na co pozwala konfiguracja. Nagłówek X-Environment ustawiony na production zapobiega zapisywaniu danych produkcyjnych przez agenta testowego, a X-Request-Source sprawi, że ślady na serwerze będą użyteczne, jeśli będziesz musiał ustalić źródło nieoczekiwanego żądania.
Sprawdź przed wdrożeniem
Sześć punktów wymaga przeglądu przed każdym wdrożeniem produkcyjnym; każdy z nich odpowiada pułapce omówionej wcześniej w tym kursie. Adres URL musi używać HTTPS z ważnym certyfikatem, w przeciwnym razie nic nie przejdzie. Etykieta musi być krótka, opisowa i unikalna w ramach konfiguracji. Opis musi odpowiadać faktycznie udostępnionym narzędziom, inaczej model spróbuje wywołań skazanych na niepowodzenie. Dozwolone narzędzia muszą być ograniczone do absolutnego minimum. Token musi pochodzić ze zmiennej środowiskowej, a nie z kodu źródłowego. Dodatkowe nagłówki muszą dokładnie odpowiadać oczekiwaniom serwera, łącznie z wielkością liter – błąd wielkości liter w X-Organization-Id powoduje cichą awarię, którą szczególnie trudno zdiagnozować.
Kluczowe wnioski
- Minimalna konfiguracja wymaga tylko
server_urliserver_label - Dodaj
server_description, aby kierować Grokiem, zwłaszcza w konfiguracjach z wieloma serwerami - Ogranicz dostęp za pomocą
allowed_tool_namesze względów bezpieczeństwa i wydajności - Użyj
authorizationiheadersdo uwierzytelniania - Obie biblioteki SDK (natywna xAI i OpenAI Responses) przyjmują te same parametry, różniąc się jedynie składnią