Narzędzia, zasoby i prompty w MCP
Na tej stronie
Zaktualizowano 2 listopada 2026 — MCP Python SDK v2. Kurs opiera się teraz na wersji 2 SDK
mcp(2.3.0 według stanu na 2 października 2026):MCPServerzastępujeFastMCP, ustawienia transportu przeniesiono do metodrun()lubstreamable_http_app(), a aplikacja wystawiona pod rzeczywistą nazwą hosta musi ją zadeklarować (transport_security). Jest to również wersja wymagana przez Mistral SDK: dodatekmistralai[agents]wymagamcp>=2.2.0,<3.0. Źródła: Co nowego w v2 · Przewodnik migracyjny · Wdrażanie i skalowanie.
Trzy możliwości, trzy intencje
Serwer MCP może udostępniać klientom trzy rodzaje możliwości. Nie są one wymienne: każda z nich odpowiada innemu potrzebie, a ich mylenie prowadzi do tworzenia serwerów, z których modelowi trudno korzystać. W tej lekcji przeanalizujemy je po kolei, zanim zajmiemy się kluczowym dla jakości serwera pytaniem: ile narzędzi stworzyć i jakiej powinny być granularity.
Narzędzia: funkcje wykonywalne
Narzędzia to najczęściej wykorzystywana możliwość tego protokołu. Narzędzie to funkcja, którą model może zdecydować się wywołać, aby wykonać akcję lub pobrać informacje. Jej definicja opiera się na czterech elementach: unikalnej, opisowej nazwie (create_issue, get_weather), tekstowym opisie informującym model, kiedy należy ją wywołać, schemacie JSON dla parametrów wejściowych z ich typami i ograniczeniami oraz formacie zwracanym – najczęściej tekście lub JSON-ie.
from mcp.server.mcpserver import MCPServer
app = MCPServer("My Server")
@app.tool()
def get_weather(latitude: float, longitude: float) -> str:
"""Pobiera aktualną pogodę dla podanych współrzędnych.
Args:
latitude: Szerokość geograficzna w stopniach dziesiętnych (-90 do 90)
longitude: Długość geograficzna w stopniach dziesiętnych (-180 do 180)
Returns:
Tekstowy opis aktualnej pogody
"""
# Logika wywołania API pogodowego
return f"Słonecznie, 22°C w ({latitude}, {longitude})"
Nie lekceważ opisu i typowania: model nie widzi niczego więcej. Nie ma dostępu do Twojego kodu, nie potrafi odgadnąć Twoich intencji ani przetestować wywołania, by sprawdzić, co się stanie. Niejasne opisy lub źle typowane parametry mechanicznie prowadzą do błędnych wywołań.
Kilka nawyków sprawi, że Twoje narzędzia będą znacznie bardziej niezawodne. Nazywaj je zgodnie z tym, co robią – book_restaurant mówi wszystko, process_request nie mówi nic – i opisuj zarówno akcję, jak i zwracaną treść, ponieważ model musi przewidzieć, co otrzyma. Zawsze annotuj parametry w Pythonie i pisz ustrukturyzowane docstringi z sekcjami Args i Returns: to one zasilają schemat widoczny dla modelu. Na koniec zwracaj czytelne wartości, a nie nieprzejrzyste identyfikatory; narzędzie zwracające "Jan Kowalski" pozwala modelowi ułożyć zdanie, podczas gdy narzędzie zwracające UUID zmusza go do zgadywania.
Zasoby: dane do odczytu
Zasoby udostępniają dane, które klient może odczytać bez skutków ubocznych. Różnica względem narzędzi sprowadza się do jednego czasownika: narzędzie coś robi, zasób coś zawiera. Zawartość pliku konfiguracyjnego, baza wiedzy, dokumentacja API czy aktualny stan systemu to wszystko naturalne zasoby.
@app.resource("config://database")
def get_db_config() -> str:
"""Aktualna konfiguracja bazy danych."""
return json.dumps({
"host": "localhost",
"port": 5432,
"database": "production"
})
Każdy zasób jest identyfikowany przez URI – config://database, file:///path/to/doc – które klient może列出, a następnie odczytać na żądanie. W praktyce używa się ich rzadziej niż narzędzi, ponieważ proste narzędzie zwracające dane pokrywa większość potrzeb. Pozostają użyteczne, gdy chcesz opublikować dane statyczne lub półstatyczne bez logiki wykonawczej stojącej za nimi.
Prompty: wielokrotnego użytku szablony
Prompty MCP to parametryzowalne szablony, które serwer udostępnia. Służą do dzielenia się sprawdzonymi instrukcjami dla danego zadania, zamiast pozwalać każdemu na wymyślanie własnego sformułowania.
@app.prompt()
def code_review(language: str, code: str) -> str:
"""Generuje prompt do recenzji kodu dla podanego języka."""
return f"""Jesteś ekspertem w języku {language}.
Przeanalizuj poniższy kod i zidentyfikuj:
1. Potencjalne błędy
2. Problemy z wydajnością
3. Poprawki czytelności
Kod do analizy:
```{language}
{code}
```"""
To zastosowanie ma największy sens w środowisku zespołowym. Starszy programista koduje swoje prompty do recenzji kodu, debugowania czy analizy architektury w serwerze MCP, a cały zespół uzyskuje do nich dostęp ze swoich klientów, zachowując tę samą jakość instrukcji.
Negocjacja możliwości
Gdy klient łączy się z serwerem, fazie negocjacji poprzedza każde użycie:
- Klient żąda możliwości serwera
- Serwer odpowiada listą swoich narzędzi, zasobów i promptów
- Klient przedstawia te możliwości modelowi językowemu
- Model wykorzystuje opisy, aby zdecydować, co wywołać
Negocjacja ta jest dynamiczna, co stanowi właściwość, którą można wykorzystać: ten sam serwer może ogłaszać różne możliwości w zależności od podłączonego użytkownika lub kontekstu wywołania – konto administratora widzi narzędzia, których konto tylko do odczytu nigdy nie zobaczy.
Ile narzędzi na serwer?
Pytanie wydaje się trywialne, a jednak warunkuje wskaźnik błędów Twojego agenta. Utrzymuj swoje serwery skupione: trzy do dziesięciu dobrze zdefiniowanych narzędzi działa lepiej niż pięćdziesiąt ogólnych. Powyżej pewnej objętości model rozprasza swoje wybory i kończy, wywołując niewłaściwe narzędzie lub nakładając niepotrzebne wywołania.
Jeśli Twój zakres funkcjonalny jest szeroki, podziel go na kilka wyspecjalizowanych serwerów – jeden do operacji Git, jeden do zarządzania projektami, jeden do monitoringu. Klient potrafi połączyć się z wieloma serwerami jednocześnie i aktywować tylko te wymagane przez bieżące zadanie, co sprowadza się do ładowania użytecznego kontekstu, a nie całego katalogu.
Ostatni kompromis zasługuje na Twoją uwagę: granularity. Udostępnienie trzech narzędzi do listowania restauracji, sprawdzania dostępności, a następnie rezerwacji zmusza model do orchestracji sekwencji, z ryzykiem błędu na każdym kroku. Pojedyncze narzędzie przepływu pracy – book_restaurant – enkapsuluje całą sekwencję, redukuje liczbę rund komunikacji i przenosi logikę biznesową tam, gdzie jest testowalna: do Twojego kodu.
Kluczowe wnioski
- Narzędzia = wykonywalne akcje (90% przypadków użycia), wymagają precyzyjnego opisu i typowania
- Zasoby = dane do odczytu przez URI, bez skutków ubocznych
- Prompty = szablony wielokrotnego użytku, przydatne dla zespołów
- Utrzymuj swoje serwery skupione (maksymalnie 3–10 narzędzi)
- Preferuj narzędzia przepływu pracy zamiast zbyt drobnoziarnistych narzędzi
- Jakość opisu determinuje wydajność modelu