Opis i dozwolone narzędzia
Na tej stronie
Dwa opcjonalne mechanizmy, dwa zupełnie różne efekty
Adres URL i etykieta wystarczą, aby nawiązać połączenie, ale nie mówią modelowi Grok, jak ma korzystać z serwera. Dwa opcjonalne parametry wypełniają tę lukę i wzajemnie się uzupełniają: server_description wyjaśnia, do czego służy serwer, natomiast allowed_tools – lub allowed_tool_names w zależności od używanego SDK – decyduje, czego serwer może dotknąć. Pierwszy kieruje, drugi ogranicza.
server_description: nadaj modelowi kontekst
Ten parametr dostarcza modelowi Grok opis możliwości serwera w języku naturalnym. Model wykorzystuje go do podjęcia decyzji: czy powinien odpytać ten serwer, inny, czy może żaden?
mcp(
server_url="https://api.example.com/mcp",
server_label="docs",
server_description="Serwer dokumentacji technicznej. Umożliwia wyszukiwanie artykułów, przeglądanie przewodników i pobieranie przykładów kodu dla wewnętrznego API."
)
Bez tego opisu Grok ma do dyspozycji jedynie indywidualne nazwy i opisy udostępnionych narzędzi. Działa to, ale model rozumuje bez szerszego obrazu: widzi zbiór narzędzi, nie wiedząc, co tworzą one collectively. Dobry opis daje mu trzy rzeczy, których żadna nazwa narzędzia nie jest w stanie przekazać: kiedy ten serwer jest właściwy, a kiedy inny, jaki typ żądań należy do niego kierować oraz – co często pomijane, a bywa decydujące – czego serwer nie robi, co pozwala uniknąć wywołań skazanych na niepowodzenie.
Napisz ten opis tak, jakbyś wyjaśniał działanie usługi koledze dołączającemu do projektu. Bądź konkretny: „Baza technicznej dokumentacji produktu“ jest użyteczna, podczas gdy samo „Dokumentacja“ już nie. Wymień działania, które są faktycznie możliwe, np. „umożliwia wyszukiwanie, odczyt i aktualizację zgłoszeń“. Jeśli zakres jest ograniczony, zaznacz to wyraźnie: informacja „dostęp tylko do odczytu, bez możliwości modyfikacji“ uchroni model przed podjęciem nieudanej próby.
allowed_tools: zawężenie zakresu
Domyślnie połączenie modelu Grok z serwerem MCP wstrzykuje do kontekstu modelu wszystkie narzędzia udostępniane przez ten serwer, bez wyjątku. W przypadku systemu CRM oznacza to, że tworzenie, modyfikowanie i usuwanie kontaktów są dostępne tak samo jak ich wyszukiwanie.
mcp(server_url="https://api.example.com/mcp",
server_label="crm")
# Grok widzi WSZYSTKIE narzędzia: create_contact, update_contact,
# delete_contact, search_contacts, export_data itd.
Parametr allowed_tool_names odwraca to zachowanie, ustanawiając explicitzną białą listę. Wszystko, czego na niej nie ma, staje się dla modelu niewidoczne.
mcp(server_url="https://api.example.com/mcp",
server_label="crm",
allowed_tool_names=["search_contacts", "get_contact_details"])
# Grok widzi tylko search_contacts i get_contact_details
Dlaczego ograniczać, nawet jeśli wszystko działa?
Pierwszym powodem jest bezpieczeństwo, które wynika z zasady najmniejszych uprawnień. Jeśli Twoja aplikacja potrzebuje tylko odczytu, nie zostawiaj w zasięgu modelu narzędzi do modyfikacji lub usuwania. Udany atak typu prompt injection – złośliwa instrukcja przemycana w dokumencie analizowanym przez Grok – nie będzie w stanie wywołać delete_contact, który nigdy nie został udostępniony. Biała lista zamienia potencjalny incydent w nieistotne zdarzenie.
# Tylko odczyt dla publicznego chatbota
allowed_tool_names=["search_database", "get_record", "format_data"]
Drugim powodem jest wydajność. Każde udostępnione narzędzie zajmuje miejsce w oknie kontekstowym, ponieważ muszą się tam zmieścić jego nazwa, opis i schemat parametrów. Serwer MCP publikujący pięćdziesiąt narzędzi zużywa considerable volume, zanim użytkownik zada w ogóle jakieś pytanie. Redukując liczbę narzędzi do pięciu naprawdę użytecznych, odzyskujesz to miejsce dla tego, co najważniejsze: samej rozmowy.
Trzecim powodem jest precyzja. Im obszerniejszy katalog, tym bardziej model waha się między podobnymi narzędziami – dwa narzędzia o zbliżonych opisach prowadzą do niestabilnych wyborów z jednego wykonania na drugie. Katalog ściśle dopasowany do Twojego przypadku użycia sprawia, że wybór staje się znacznie bardziej niezawodny.
Połącz oba mechanizmy
Rezultat staje się naprawdę czysty, gdy połączysz oba parametry, pod warunkiem że opowiadają tę samą historię.
mcp(
server_url="https://api.example.com/mcp",
server_label="crm",
server_description="CRM tylko do odczytu. Wyszukiwanie i przeglądanie kontaktów oraz firm.",
allowed_tool_names=["search_contacts", "get_contact", "search_companies", "get_company"]
)
Tutaj opis zapowiada dostęp tylko do odczytu, a biała list gwarantuje to technicznie. Strzeż się sytuacji odwrotnej, która zdarza się częściej, niż myślisz: opis odziedziczony po poprzedniej wersji, obiecujący możliwości zapisu, które zostały już usunięte z białej listy. Model spróbuje wykonać wywołanie, poniesie porażkę, a Ty stracisz czas na szukanie błędu, którego nie ma. Zawsze przeglądaj te dwa parametry razem, nigdy osobno.
Kluczowe wnioski
server_descriptionpomaga modelowi Grok zrozumieć, kiedy użyć tego serwera MCP- Bez
allowed_toolswszystkie narzędzia serwera są wstrzykiwane do kontekstu - Ograniczanie narzędzi wzmacnia bezpieczeństwo, wydajność i precyzję
- Połącz opis z ograniczeniami, aby uzyskać optymalną kontrolę
- Napisz opis jako wyjaśnienie w języku naturalnym, dotyczące możliwości serwera