Практычныя прыемкі: Як функцыонуюць серверы MCP: Паўныя інструкцыі пра тое, што я вывучыў
Практычныя прыказкі: Паспраўнік MCP-сервераў: Ўжоўныя інструкцыі па там, што я вывучыў: контракты, перакананні і слоты для коду для команд, якія викорыстоўваюць гэты патэрн.
У гэтым карыце парадоксальнае шлях ад сыр'ёў да рабочай системы для: MCP Servers Explained: A Complete Guide to What I Learned Deploying One to AWS EC2. Акцэнт ставіцца на практычныя крокі, чыстае перакананне і код, які можна проста падставіць у репазітарый без неабяснення меты.
Што ўключаецца
У раздзеле «Што ўключаецца» неабходна практычна апісацыя вхідных дадзеных, адпаведальнага за крок і крэтарыяў завершэння працы перш чым змяніць код. Аператары должны магчымае перадзеяць крок з вядомай точкі контролю без неабяснення схованага стану. Штадзію трэба спрыятаць як кантракт між вхіднымі дадзенымі і перакананымі выходнымі рэзультатамі. Неабходна даць назвы артыфактам, практычна апісацыя крэтароў успеху і не дазволяць тыхамую частковае завершэння працы. Аутентыфікацыя трэба адбывацца на в'язку, а практычна автарызацыя — на роўні дадзеных. Толькі токэн-носіцель не ўтварае межы тэнанты.
Асновы
Для стадіі «Асалейнія» неабходна прадзеўжэнне вхідных дадзенняў, апыліканніка, які выконвае крок, і крэатарыяў выходу пры перадзеўжэнні коду. Аператары павінны магчымаць перывыканне крока з вядомай точкі контролю без неабходнасці адгадвання скрытага стану. Запісваюцца часы выконання і косты токенаў або запытак праза функцыйнае рэзультат. Відкрытыя даннія пра косцы запобегаюць неспадзеваным рачункам, калі процес пераходзіць з дэмавайнага сераўера ў спадзеленыя сэрвісы. Аутентыфікацыя выканаўцца ў шлюзе, а павторная автарызацыя — у роўні дадзенняў. Толькі токен-носіцель не є межай апылікання.
Што на самай працэ запрацоўвае MCP
У раздзеле «Што на самай працо ўключае MCP» неабходна прадзефінавацыя вхідных дадзенняў, адпаведальнага за крок і крэатарыяў завершэння працы перад зменым коду. Аператары должны магчымае перзапускіць крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Конфігурацыю трэба залічыць паза кодам прыемліка. Файлы сераўнавальнага сяродовішча, хранілішчы секрэтных дадзенняў і флагі функцыйяй должны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць, не чытаяўшы весь ланцуг задач. Аутентыфікацыя павінна выконвацца на воратах, а пераправерка — у роўні дадзенняў. Сам токен-носіцель не є межай арендаванага ресурсу.
Чаму деталі развяртання ўзьмоцны проблема
Кабы дакле былі заданыя падробнасці аплявлення, неабходна ўзначыць вхідныя даны, адпаведальнага за крок і критэрыя завершэння пры зміне коду. Аперацыйныя працавнікі должны магчымае запускаць крок з вядомай точкі контролю, не спрабоўваючы здогадвацца пра схованы стан. Неабходна задокументаваць як шлях успеху, так і шлях вярнення. Перапрыбуткі, людзкіе перакрыцця і обробка некоректных паведамленняў є часткай продукту, а не чымсь, што дадаецца пазней. Аутентыфікацыя выканаўцаяся ў шлюзе, а прабачэнне праваў — у роўні дадзенняў. Толькі токэн-носіцель не є межай арендаванага ресурсу.
Полная архітэктура
Для стадіі «Полная архітектура» неабяцо практычная вказаць інпутаў, адпаведальнага за крок і крэтарыяў завершэння працы перад зменым коду. Аперацыйныя працавнікі павінны магчымае перзапускаць крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Лепш выбіраць маленькія, тэставаныя елементы замест большых скрыптаў. Калі крок не выйшоў, прычына неудачы павінна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцуг задач. Автентыфікуйцеся на входзе і практычная автарызуйцеся на роўні дадзенняў. Толькі токэн-носіцель не є межай адпаведальнасці.
AI Client ── HTTPS POST ──▶ nginx (TLS termination, auth check, reverse proxy)
│
▼
MCP Server Process
(Streamable HTTP transport)
│
┌────────────┴────────────┐
Tools Resources
Для стадіі «Полная архітектура» неабяцо пазначыць вхідныя даны, адпаведнага адпаведальнага за крок і крэтыяры завершэння пры змены коду. Аперацыйныя працавнікі должны магчымае запускаць крок з вядомай точкі контролю, не прабуючы вычысляць захаваны стан. Запісваць час выконання і кост токенаў або запытаў разам з функцыйнальнымі рэзултатамі. Відразы костаў з самага пачатку запобегае неспакойным рахункам, калі процес пераходзіць з дэмавай версіі ў спяльныя среды.
Паспяшанне основных слоёў
Калі працюеце над этапам «Core Layers Explained», спачатку запісайце умовы працы: неабяжлівыя даннэ, сигнал успеху і тое, што выходзіць пад частыя неудачы. Такі список контролю дапамагае заліцварыць пазнейшыя змены ў кодзе. Зберагаюце настройкі праза код аплікацыі. Файлы сераўнавання, хранільнікі секрэтных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць адбавіць аудыт без неабяжлівага чытання всей структуры. Запісвайце назву інструмента, хэш параметраў, час адклікання і рынак кожнага вызову. Без такога лёгкага следу дэбагаванне агента губіць гады часу.
1. Транспорт: Streamable HTTP
Калі працюеце над стадзіяй 1 Transport Streamable HTTP, спачатку запісайце умовы вярбунка: неабяжлівыя данні, сігнал успеху і тое, што выходзіць у разе частковага нявыпання. Такі список контроля дапамагае заліцьваты змяны ў кодзе чыстымі.
location /mcp {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header Authorization $http_authorization;
proxy_http_version 1.1;
proxy_read_timeout 300s;
}
2. Аутентыкацыя: токены-несучыя (пачаткова точка, а не канечная)
Калі працуеце над стадзіям 2 «Токены аутантыкацыі», спачатку запісайце умовы вярбання: неабяжлівыя данні, сигнал успеху і тое, што выходзіць па частковай нявыполненасці. Такі список дапамагае залічыць пазнейшыя змены ў кодзе.
from fastapi import Request, HTTPException
VALID_TOKEN = "your-rotated-secret-token"async def verify_bearer(request: Request):
auth = request.headers.get("authorization", "")
if auth != f"Bearer {VALID_TOKEN}":
raise HTTPException(status_code=401, detail="Unauthorized")
3. Безстановасць — аснова перапісву з липня 2026 года
Этап «Безстановасць — аснова» працюе найэфектывней, калі яго розглядаць як меравальную плошчу. Зберагачыце адны ідеальны прыклад работы, адну ситуацыю неудачы і прыметкі па поверненню да пярвоначальнага стану пры розширэнні масштаба. Храніце настройкі пазначыцельна ад коду прыемлівача. Файлы сяродавішняе сераўісу, хранальнікі секрэтных данных і пазначкі функцый крануцца на аднай адзіне пазе, якую аператары можаць пераглядаць без неабяжнага чытання всіх элементаў системы. Адкрывайце інструменты з вузкімі схемамі і чытальнымі пазначкамі па бокавых эфектах. Хостам неабходна знаты, якія запыткі мутуюць стан, перш чым яны автаматычна схваляюць іх.
4. Багатаэтапныя запыткі (запыткаў к адпаведніку ў ходзе виканання)
Этап 4 «Запыткі з мнагакратнымя паходамі-выходамі» працуе наўлежна, калі яго розглядаюць як мерыемую плошчу. Зафіксавайце адны ідеальны прыклад, адзін прыклад неудачы і запіс пра анулювання перад расшырэннем масштабаў. Дакументавайце як шлях успеху, так і шлях вяснавання. Перапрыбуткі, людзкія контралі і обработка некоректных паведамленняў є часткай продукту, а не наступнымэю дапрацоўкай. Адкройце інструменты з вузкімі схемамі та чысткімі пазначэннямі пабочных эфектаў. Хостам неабходна знать, якія запыткі меняюць стан, перш чым яны автаматычна схваляюць іх.
5. Паўнейшая захоўка автарызаціі: OAuth 2.1, PKCE і паказчыкі рэсурсаў
5-й этап забезпечэння безпекі автарызацыі OAuth працюе наявнасць калі яго расследжваюць як меравальную плошчу. Зберагачыце адны ідеальны прыклад роботы, адзін кейс неудачы і прыметкі па адвярненню роботы пры расшырэнні дыячнасці. Валіце маленькія, тэставальныя элементы замест большых скрыптов. Калі якісь крок не выйшае, прычына неудачы павінна вказываць на адную адпаведальнасць, а не на заплутаны ланцужок дзеянняў. Адкрывайце інструменты з вузкімі схемамі та чысткімі пазначэннямі побачных наследкаў. Хостам неабходна знаты, якія вызовы мутуюць стан, перш чым яны будуць автаматычна затверджвацьыя ўпраўленні. 5-й этап забезпечэння безпекі автарызацыі OAuth працюе наявнасць калі яго расследжваюць як меравальную плошчу. Зберагачыце адны ідеальны прыклад роботы, адзін кейс неудачы і прыметкі па адвярненню роботы пры расшырэнні дыячнасці. Запісвайце час выканання та кост токена або запыту разам з функцыйнальнымі рэзультатамі. Відразлівасць костаў з самага пачатку запобегае неспакойным рахункам, калі процес пераходзіць з дэмовай среды ў спяльнаныя сераўы.
6. Палітіка знявання падтрымкі та фрэймворк расшырэнняў
Для політы та стадій зняцья з выкарыстоўвання 6 неабходна прадзефінаваць вхідныя даны, адпаведальную особу за кожны крок і критэрыя завершэння перад змінайом коду. Аператары должны магчымаць перзапуск крока з вядомай точкі контролю, не падозрываючы прыхованы стан. Конфігурацыю трэба знаходзіць за межамі коду прыкладнення. Файлы сераўнавання, хранільнікі секрэтных дадзеных і флагі функцыйяў должны быць у аднам месца, якое аператары можаць пераглядаць, не чытаяўшы весь ланцуг задач. Автентыфікацыя павінна выконвацца на шлюзе, а пераправерка — на роўні дадзеных. Сам токен-носіцель не є межай арендаванага ресурсу.
Паследовы аналіз з начала да канца
Для стадіі парадоксальнага аналізу з самага початку даўжыны до канца неабходна прадзефінаваць вхідныя даны, адпаведальную особу за кожны крок і критэрыя завершэння працы перад змінайом коду. Аператары должны магчымае запускаваць крок з вядомай точкі контролю, не прабуючы спадарожваць схованы стан. Неабходна адзначыць як шлях успеху, так і шлях вярнення да нормальнага стану. Перапрыбуткі, людзкія перакрыцця і обробка некоректных паведамленняў є часткай продукту, а не яго пазнейшага дапрацоўвання. Аутентыфікацыя выконваецца на воратах, а паўторная автарызацыя — на роўні дадзенняў. Толькі токэн-носіцель не є межай адпаведнага тэнанту.
Спецыяльныя случаі
Для стадіі «Спецыяльныя случаі» неабходна прадзеўжыць вхідныя даны, выклікача кроку і крэтыніяя з выходам пры перадзеўжанні коду. Аператары должны магчымае перзапускнуць крок з вядомага пункту контролю, не спрабоўваючы здагадвацца пра схованы стан. Лепш выбіраць маленькія, тэставаныя елементы замест абмежлёных скрыптав. Калі крок не выйшаў, прычына нехасабності павінна вказваць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцоўку. Автентыфікуйцеся на входзе і паўторна автарызуйцеся на роўні дадзенняў. Толькі токэн-носіцель не є межай арендаванага ресурсу. Для стадіі «Спецыяльныя случаі» неабходна прадзеўжыць вхідныя даны, выклікача кроку і крэтыніяя з выходам пры перадзеўжанні коду. Аператары должны магчымае перзапускнуць крок з вядомага пункту контролю, не спрабоўваючы здагадвацца пра схованы стан. Запісвайце час выконання і кост токэна або запыту разам з функцыйнымі рэзультатамі. Відразлівасць костаў з самага пачатку запобегае неспакойным рахункам, калі процес пераходзіць з дэмавайнага режыма ў спяльныя среды.
Зялежнасць ад размеру та проблемы практычнага выкарыстоўвання
Калі працуеце над стадзіяй развіцья зялежнасці ад размеру, спачатку запішыце угоду: неабяжлівыя даннэ, сігнал успеху і тое, што выканаецца у разы частковага нявыпалення. Такі список контроля дапамагае заліцьваты змяны ў кодзе. Храніце настройкі парадульна ад коду прыемліка. Файлы сераўнавальнага сэрвісу, хранілішчы секретных данных і флагі функцый крануцца ў аднам месцы, якое аператары можаць пераглядаць без неабяжлівага чытання всей структуры. Запішыце назву інструмента, хэш параметраў, час адклікання та рынак кожнага вызову. Без такога лёгкага следу час на дэбагаванне губіцца за гадзіны.
Прыклады коду
Калі працюеце над стадзіяй «Прыклады коду», спачатку запісайце умовы кантракту: неабяжлівыя даннэ, сігнал успеху і тое, што выходзіць пад частыя неудачы. Такі список контроля дапамагае заліцварваць будучыя змены ў кодзе. Документавайце як шлях успеху, так і шлях вярнення. Перапрыбуткі, людзкіе перакрыцця і обробка некоректных паведамленняў є часткай продукту, а не дадатковым дошліваннем пазней. Зяўляйце логі з назвай інструмента, хэшам аргументаў, часам затрымкі і рэзультатам кожнага вызову. Без такога следу дэбаггінгавы агент траціць гадзіны на безрезультатныя прабавы.
async def call_tool_with_resume(client, tool_name, params):
result = await client.call_tool(tool_name, params)
if result.get("type") == "InputRequiredResult":
answers = collect_answers(result["questions"])
return await client.call_tool(
tool_name,
{**params, "answers": answers, "requestState": result["requestState"]},
)
return result
Пашчэрпаныя падступкі
Калі працуеце над стадзіяй «Звычныя падачы», спачатку запісайце умовы кантракта: неабяжлівыя данні, сигнал успеху і тое, што выходзіць у разе частковай падачы. Такі список контроля дапамагае заставіць пазнейшыя змены коду быць чыстымі. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок падае, падача должна вказваць на адну адпаведную адпаведальнасць, а не на заплутаны ланцюг задач. Запісвайце назву інструмента, хэш параметраў, час адклікання і рынак кожнага вызову. Дэбаггін без такога следу марнуюць гадзіны. Калі працуеце над стадзіяй «Звычныя падачы», спачатку запісайце умовы кантракта: неабяжлівыя данні, сигнал успеху і тое, што выходзіць у разе частковай падачы. Такі список контроля дапамагае заставіць пазнейшыя змены коду быць чыстымі. Запісвайце часы выканання і кост токенаў або запытаў разам з функцыйнальнымі рынакамі. Візуабілізація костаў з самага пачатку запобегае неспакойным рахункам, калі праця пераходзіць з дэмаверсіі ў спакульнаныя сераўы.
Аптальнае практыкаванне ў працэсе вырабніцтва
Этап наявнасці найкращых практыкаў у працэсе вырабаткі работае наявнасцю, калі яго розглядаюць як параметр, які можна вымерыць. Перш чым расширваць сферу дзеяння, неабходна зафіксаваць адны ідеальны прыклад роботы, адзін прыклад неудачы і запіс пра процедуру вярнення да пачатковага стану. Конфігурацыю трэба знаходзіць паза кодам прыемліка. Файлы сяродавішча, хранільнікі секрэтных данных і пазначкі функцый належыць у аднам месца, дзе аператары можаць аудытуваць іх, не чытаючы весь код. Неабходна выклікваць інструменты з вузкімі схемамі та чысткімі пазначкамі пра побачныя наследкі. Хостам неабходна знаты, якія вызовы мутуюць стан, перш чым вони автаматычна схваляюць іх.
Заключэнне
Этап завершэння працюе найкраща, калі яго розглядаць як вимерную плошчу. Зберагачыце адны ідеальны прыклад роботы, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць масштабы.
Чэк-ліст для эксплуатацыі
Этап чэк-ліста для эксплуатацыі працюе найкраща, калі яго розглядаць як вимерную плошчу. Зберагачыце адны ідеальны прыклад роботы, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць масштабы.
Разглядзіце этап як кантракт межа вхіднымі даннымі і перакананымі выходнымі рэзультатамі. Даўце назвы артыфактам, задаце критэрыя успеху і адмовіцеся ад мовчанкавага частковага завершэння.
Адаптавайце інструменты з вузкімі схемамі та чыткімі пазначэннямі побачных эфектаў. Хостам неабходна знаты, якія запыткі меняюць стан, прычым яны будуць автаматычна затверджаны.
Калі дозволяе бюджет, дадзіце тэст на перакананне, які працюе з критычным маршрутом у CI за дапамою фікстураў, а не з рэальнымі платнымі API.
Запісвайце час выканання адпаведна косць токенаў чы роезпытакоў па боку функцыйнальных рэзультатаў. Відразлівае відображэнне косцей запобегае неспакою, калі маршрут пераходзіць з дэмаверсіі ў спакульнаныя сераўсы.
Адаптавайце інструменты з вузкімі схемамі та чыткімі пазначэннямі побачных эфектаў. Хостам неабходна знаты, якія запыткі меняюць стан, прычым яны будуць автаматычна затверджаны.
Перад паўзлом на вышэйшую версію заморозьце версіі, зафіксаваце ідеальны транскрыпт для критычнага маршрута і паказваце крокі для адворачэння. У спакульных сераўсы неабходны ліміты на колькасць запытакоў, пераглед прыналежнасці та чысткі власнік для змены секрэтных даных. Валіце простую надзяйнасць працы над крэатывнымі, адзінразовымі дэмамі.
Запіскі для пакета a75b5a936f62: не трэба кантрацяваць ключы прадастоўцаў у репазітарые, задаць максімальную кантроль на токены на адну сесію, а таксама зберагчы транскрыпціі праза фіксатуры eval, каб пазнейшыя замены модэляў заставаліся парабелнымі.