MCP Dev Guide: pisanie własnego serwera MCP

Czego się nauczysz

• Jak myśleć o architekturze własnego serwera MCP, zanim napiszesz pierwszą linijkę kodu
• Jak projektować tools, resources i prompts tak, żeby agent realnie z nich korzystał
• Jak debugować, rozwijać i utrzymywać serwer MCP w VS Code

Najpierw projekt capability, potem kod

To najważniejsza rada z całego MCP Dev Guide.

Większość błędów przy tworzeniu własnego serwera MCP nie wynika z transportu ani SDK. Wynika z tego, że autor od razu przechodzi do implementacji, nie wiedząc jeszcze, jakie capability powinien wystawić i w jakim kształcie.

Nie każdy problem wymaga własnego serwera MCP

Dokumentacja deweloperska uczciwie sugeruje, że czasem lepszym wyborem będzie extension tool.

MCP ma największy sens, gdy:

• chcesz przenośną integrację
• chcesz działać także poza samym VS Code
• zależy Ci na otwartym standardzie

Jeśli potrzebujesz bardzo głębokiej integracji z API edytora i dystrybucji przez Marketplace, rozszerzenie może być trafniejszą ścieżką.

Zacznij od trzech pytań projektowych

Zanim wybierzesz SDK, odpowiedz sobie:

1. Czy agent ma coś robić, czy głównie czytać kontekst?
2. Czy capability powinno być tool, resource czy prompt?
3. Czy operacja musi mieć uprawnienia zapisu, czy wystarczy read-only?

To pytania ważniejsze niż wybór języka.

Dobre MCP tools są małe i ostre

Best practices z docsów są bardzo sensowne:

• operacje mają być skupione i atomowe
• błędy mają być czytelne
• input ma być walidowany
• długie operacje powinny raportować postęp

To świetnie pasuje do pracy agenta. Agent dużo lepiej radzi sobie z zestawem prostych, jasno opisanych capability niż z jednym narzędziem robiącym pięć rzeczy na raz.

readOnlyHint to nie detal

W sekcji Tools pojawia się bardzo ważna rzecz: adnotacje narzędzi, w tym readOnlyHint.

To pole ma realne znaczenie operacyjne, bo VS Code nie pyta o potwierdzenie dla narzędzi oznaczonych jako read-only.

To oznacza, że dobre oznaczanie narzędzi wpływa bezpośrednio na UX i model bezpieczeństwa.

Jeżeli narzędzie tylko pobiera albo analizuje dane, warto to opisać jawnie i uczciwie.

Resources są niedoceniane

Wiele osób projektuje serwer MCP jak API do akcji. A tymczasem resources bywają równie cenne.

Resource pozwala udostępnić dane w sposób, który użytkownik albo agent może dołączyć jako kontekst. To może być:

• log aplikacji
• snapshot stanu systemu
• tabela z bazy
• raport wygenerowany przez narzędzie

Jeśli coś ma przede wszystkim zasilać myślenie modelu, resource bywa lepszym wyborem niż tool.

Prompts też są capability serwera

To bardzo praktyczna rzecz. MCP prompt może wystawić gotowy slash command w postaci mcp.server.prompt.

Czyli serwer może dawać nie tylko operacje i dane, ale też gotowe workflow dla użytkownika.

To jest szczególnie przydatne wtedy, gdy integracja ma kilka typowych zastosowań i chcesz użytkownika poprowadzić po dobrej ścieżce.

Auth i sampling trzeba projektować świadomie

Nowoczesny MCP w VS Code wspiera autoryzację zgodną ze specyfikacją i sampling.

Auth oznacza, że serwer może działać w imieniu użytkownika wobec zewnętrznej usługi.

Sampling oznacza, że serwer może sam wykonywać requesty do modeli użytkownika, jeśli dostanie na to zgodę.

To są bardzo mocne capability. Trzeba je włączać tylko wtedy, gdy naprawdę rozwiązują problem, bo od razu podnoszą poziom odpowiedzialności za projekt serwera.

Nazwy w MCP mają znaczenie większe niż się wydaje

Docs dają konkretne konwencje nazewnicze:

• tool name: snake_case, opisujące akcję i obiekt
• input parameters: camelCase
• resource names: czytelne, opisowe
• prompt names: jednoznaczne i zorientowane na użycie

To nie jest kosmetyka. Agent i użytkownik widzą te nazwy w pickerach, dialogach i promptach. Złe nazewnictwo obniża skuteczność nawet dobrego capability.

VS Code daje sensowny dev loop dla MCP

To ważna część guide’a: development mode.

W konfiguracji serwera możesz ustawić dev.watch i dev.debug, dzięki czemu VS Code pomaga Ci restartować i debugować serwer podczas pracy.

Do tego dochodzą:

• output log serwera
• MCP: List Servers
• restart i podgląd statusu

Bez tego utrzymanie własnego serwera szybko staje się męczące.

Myśl o dystrybucji wcześniej niż później

Guide pokazuje kilka ścieżek dodawania serwera do VS Code:

• konfiguracja w mcp.json
• globalna konfiguracja
• autodiscovery
• extension provider
• install URL vscode:mcp/install

To ważne, bo inaczej projektuje się serwer dla własnego zespołu, a inaczej capability, które ma być łatwo instalowane przez innych.

Ćwiczenie praktyczne

Zaprojektuj minimalny serwer MCP dla własnego projektu. Na papierze wystarczy.

Uwzględnij:

• jedno read-only tool
• jeden resource
• jeden prompt
• nazwy i parametry wejściowe
• sposób autoryzacji albo świadomą decyzję, że auth nie jest potrzebny
• sposób debugowania w development mode

Na końcu odpowiedz, które capability agent ma wykrywać automatycznie, a które użytkownik powinien wywoływać świadomie.

Kluczowe wnioski

• Najtrudniejsza część własnego MCP to nie kod, tylko dobry projekt capability.
• Tools, resources i prompts służą do różnych rzeczy i nie powinny być mieszane bez potrzeby.
• readOnlyHint, nazewnictwo i walidacja wejścia mają realny wpływ na bezpieczeństwo oraz UX.
• Własny serwer MCP trzeba projektować z myślą o debugowaniu, auth i dystrybucji.

Co dalej

Własny serwer MCP daje ogromne możliwości, ale też powiększa powierzchnię zaufania. Następna lekcja domyka temat od właściwej strony: jak myśleć o bezpieczeństwie, trust promptach, sandboxingu i sekretach w świecie MCP.