Инструменти, ресурси и подкани в MCP
На тази страница
Обновено на 2 ноември 2026 г. — MCP Python SDK v2. Този курс следва версия 2 на
mcpSDK (2.3.0 към 2 октомври 2026 г.):MCPServerзаместваFastMCP, настройките за транспорт се преместват вrun()илиstreamable_http_app(), а приложението, изложено под реално име на хост, трябва да декларира това име (transport_security). Това е и версията, изисквана от Mistral SDK: допълнениетоmistralai[agents]изискваmcp>=2.2.0,<3.0. Източници: Какво е ново във v2 · Ръководство за миграция · Разполагане и мащабиране.
Три възможности, три намерения
Един MCP сървър може да изложи три типа възможности пред своите клиенти. Те не са взаимозаменяеми: всяка отговаря на различна нужда и объркването между трите води до сървъри, които моделът трудно използва. В този урок ще ги разгледаме един по един, преди да се заемем с въпроса, който определя качеството на сървъра: колко инструмента и с каква гранулярност.
Инструменти: изпълними функции
Инструментите са най-широко използваната възможност на протокола. Инструментът е функция, която моделът може да реши да извика, за да извърши действие или да извлече информация. Неговата дефиниция разчита на четири елемента: уникално и описателно име (create_issue, get_weather), текстово описание, което казва на модела кога да го извика, JSON схема за входните параметри с техните типове и ограничения, и формат на връщаната стойност – най-често текст или JSON.
from mcp.server.mcpserver import MCPServer
app = MCPServer("My Server")
@app.tool()
def get_weather(latitude: float, longitude: float) -> str:
"""Retrieves current weather for the given coordinates.
Args:
latitude: Latitude in decimal degrees (-90 to 90)
longitude: Longitude in decimal degrees (-180 to 180)
Returns:
Text description of current weather
"""
# Weather API call logic
return f"Sunny, 22°C at ({latitude}, {longitude})"
Не подценявайте описанието и типизирането: моделът не вижда нищо друго. Той няма достъп до вашия код, не може да отгатне намеренията ви и не може да тества извикване, за да види какво ще се случи. Неясните описания или лошо типизираните параметри механично водят до грешни извиквания.
Няколко навика правят вашите инструменти значително по-надеждни. Именувайте ги според това какво правят – book_restaurant казва всичко, докато process_request не казва нищо – и описвайте както действието, така и връщаното съдържание, тъй като моделът трябва да предвиди какво ще получи. Винаги анотирайте параметрите в Python и пишете структурирани docstrings с Args и Returns: те захранват схемата, която моделът вижда. Накрая, връщайте четими стойности, а не непрозрачни идентификатори; инструмент, който връща "John Smith", позволява на модела да състави изречение, докато инструмент, връщащ UUID, го принуждава да гадае.
Ресурси: данни за четене
Ресурсите излагат данни, които клиентът може да прочете без странични ефекти. Нюансът спрямо инструментите се свежда до един глагол: инструментът прави нещо, докато ресурсът съдържа нещо. Съдържанието на конфигурационен файл, база знания, документация на API или текущото състояние на система са естествени ресурси.
@app.resource("config://database")
def get_db_config() -> str:
"""Current database configuration."""
return json.dumps({
"host": "localhost",
"port": 5432,
"database": "production"
})
Всеки ресурс се идентифицира чрез URI – config://database, file:///path/to/doc – който клиентът може да изброи и след това да прочете при поискване. На практика те се използват по-рядко от инструментите, тъй като обикновен инструмент, връщащ данни, покрива повечето нужди. Те остават полезни, когато искате да публикувате статични или полустатични данни без логика за изпълнение зад тях.
Подкани: многократни шаблони
MCP Подканите (Prompts) са параметризируеми шаблони, които сървърът предоставя. Те служат за споделяне на доказали ефективността си инструкции за дадена задача, вместо всеки да преоткрива собствената си формулировка.
@app.prompt()
def code_review(language: str, code: str) -> str:
"""Generates a code review prompt for the given language."""
return f"""You are an expert in {language}.
Analyze the following code and identify:
1. Potential bugs
2. Performance issues
3. Readability improvements
Code to analyze:
```{language}
{code}
```"""
Тази употреба има най-голям смисъл в екипна среда. Старши разработчик кодира своите подкани за преглед на код, отстраняване на грешки или анализ на архитектурата в MCP сървър и целият екип получава достъп до тях от своите клиенти със същото качество на инструкциите.
Преговори за възможности
Когато клиент се свърже със сървър, фаза на преговори предшества всякаква употреба:
- Клиентът заявява възможностите на сървъра
- Сървърът отговаря със своя списък от инструменти, ресурси и подкани
- Клиентът представя тези възможности на езиковия модел
- Моделът използва описанията, за да реши какво да извика
Тези преговори са динамични и това е свойство, което може да се използва: един и същ сървър може да обявява различни възможности в зависимост от свързания потребител или контекста на извикване – администраторски акаунт вижда инструменти, които акаунт само за четене никога няма да види.
Колко инструмента на сървър?
Въпросът изглежда тривиален, но той обуславя процента на грешки на вашия агент. Поддържайте сървърите си фокусирани: три до десет добре дефинирани инструмента работят по-добре от петдесет общи. Отвъд определен обем моделът разпръсква избора си и в крайна сметка извиква грешния инструмент или натрупва ненужни извиквания.
Ако вашият функционален обхват е широк, разделете го на няколко специализирани сървъра – един за Git операции, един за управление на проекти, един за мониторинг. Клиентът знае как да се свърже с множество сървъри едновременно и да активира само онези, които са необходими за текущата задача, което се равнява на зареждане на полезния контекст, а не на целия каталог.
Един последен компромис заслужава вниманието ви: гранулярността. Излагането на три инструмента за списък с ресторанти, проверка на наличността и след това резервация принуждава модела да организира последователност, с риск от грешка на всяка стъпка. Един единствен инструмент за работен поток – book_restaurant – капсулира цялата последователност, намалява броя на往返 (round trips) и премества бизнес логиката там, където е тестваема: във вашия код.
Ключови изводи
- Инструменти = изпълними действия (90% от случаите на употреба), изискват точно описание и типизиране
- Ресурси = данни за четене чрез URI, без странични ефекти
- Подкани = многократни шаблони, полезни за екипи
- Поддържайте сървърите си фокусирани (максимум 3–10 инструмента)
- Предпочитайте инструменти за работен поток пред твърде гранулирани инструменти
- Качеството на описанието определя ефективността на модела