第1章專題需求、MCP 概念與開發環境 — MCP Server 治理平台實戰手冊

這章要學會什麼

用一張表說出「API 提供者、API 使用者、後臺管理者、MCP Client」這四種角色各自能做什麼、不能做什麼。
畫出「MCP Client → 平台 /mcp → API Gateway → 上游 REST API」的呼叫路徑，知道哪一段在檢查權限。
分清楚「API 上架」（草稿→送審→核准發布或退回→下架）跟「使用授權」（申請→審核→建立使用權）是兩條不同的流程。
用指令建立專題的 Solution，並把開發工具的版本鎖住，全班用同一版不會各自出錯。
打開「環境檢查頁」，看到 SQL Server 顯示正常、兩支示範 API 打得通。
能一句話講清楚：「註冊成功，不代表你就能呼叫 API。」

先備知識

這是第一章，沒有前面章節的東西要先讀。只要你：

會寫基本的 C#（類別、async/await 這種非同步寫法）；看得懂 HTML 和資料庫查詢語法 SQL 的 SELECT。
知道網頁溝通的 HTTP 協定裡，GET／POST 是什麼、200／201／400 這些狀態碼大概代表成功還是失敗。
電腦上已經裝好 .NET SDK、SQL Server（本機測試版即可）、以及 Visual Studio 或 VS Code。

就可以開始了。

觀念白話講

為什麼需要這個平台

假設一家公司已經做好三支現成的網路服務（術語叫 API）：查商品、查課程、開客服工單。現在想讓 AI 助理也能用這些服務，但如果直接把服務網址跟密鑰交給 AI，會馬上冒出三個麻煩：

誰都能叫：只要拿到密鑰就能用，沒辦法規定「這個人只能查商品、不能開工單」。
收不回來：員工離職了、服務要下架了，密鑰卻還在外面流通，除非把密鑰整組換掉、讓所有人一起斷線。
查不到帳：出事時完全不知道是誰、用哪個 AI 助理、什麼時候、呼叫了哪一版的服務。

這門課要做的平台，就是夾在「服務」跟「AI 助理」中間的那一層管理室：服務提供者要先登記，管理員審核通過才公開；使用者要申請、獲准了才能用；而且每一次呼叫都會重新檢查權限，並且留下紀錄。

四種角色，各自能做什麼

圖 1-1 四種角色在平台上的分工：API 提供者登錄規格→後臺管理者審核→平台 /mcp 發布成工具→API 使用者申請並授權 Client→MCP Client 代表使用者呼叫。

角色	能做什麼	不能做什麼（為什麼）
① API 提供者（會員）	建立 API 草稿、填網址／方法／參數規格、建版本、送審	不能核准自己的 API——送審跟審核一定要是不同人
② 後臺管理者（Admin）	審核上架與使用申請、停權、下架、撤銷授權	不會因為是管理員就自動取得呼叫權；不能審自己送的案子
③ 平台 /mcp	把已核准的版本公開成 AI 看得懂的「工具」，每次呼叫前都先檢查權限	不會執行使用者上傳的任意程式，只代為呼叫已登錄的服務
④ API 使用者（會員）	瀏覽已發布的服務、對某個版本提出使用申請、授權自己的 AI 應用	核准前完全看不到、也叫不到這個工具
⑤ MCP Client（AI 助理）	代表某位使用者列出工具並呼叫	只拿得到那位使用者「此刻」有效的權限，不是永久通行證

同一個人可以同時是提供者跟使用者，但送審與核准一定要分開。

MCP 跟一般網路服務（REST）是什麼關係

MCP（Model Context Protocol，模型脈絡協定）白話講就是一套「AI 助理要怎麼問伺服器有哪些工具、怎麼呼叫」的公版說明書。這門課用它的其中一種傳輸方式：所有訊息都送到平台的同一個網址 /mcp。而「上游 REST API」指的是本來就已經存在的那些服務（查商品、查課程等）。

兩者的關係是：MCP 不是取代這些服務，而是包在它們外面、專門講給 AI 聽的一層介面。AI 只需要知道工具名字跟要填哪些參數，完全不必知道背後真正的網址或密鑰是什麼。

圖 1-2 一次 MCP 工具呼叫如何轉成 REST 呼叫：MCP Client 問「有哪些工具」→平台回傳這位會員能用的清單→Client 要求呼叫某個工具→平台重新檢查權限→通過才交給 Gateway 去打真正的服務→結果連同耗時、追查代碼一起寫進呼叫紀錄再回給 Client。

兩個常見誤會：①AI 助理拿到的工具清單只是「當下的快照」，就算清單上還在，之後權限被收回，下一次呼叫一樣會被擋下；②網站登入用的 Cookie，跟 MCP 呼叫用的通行證（Access Token）是兩回事，不能混用。

兩條審核流程：上架審規格、授權審使用者

平台上其實有兩種完全不同的申請，很多人一開始會搞混：

圖 1-3 API 上架流程（審的對象是「這個版本」）：草稿→送審（內容從此凍結）→管理者審核→核准就變成已發布、退回就改完重送→之後可以停用或下架。

第一條是提供者讓自己的服務「出現在目錄上」——審的是「這個版本的規格能不能公開」。送審後內容會被凍結，不能偷改；管理者只能核准或退回，退回一定要寫理由。

圖 1-4 API 使用授權流程（審的對象是「這位會員對這個版本的使用權」）：選擇一個已發布的版本→填用途、期限、額度→管理者審核→核准就建立使用權（有效期、額度都記著）、每次呼叫都重新檢查→駁回就結案，不產生任何使用權。

第二條是使用者取得「呼叫某個已發布版本」的權利——審的是「這個人能不能用」。這條路徑上「申請被核准了」和「現在還能用」是分開記錄的兩件事：核准的歷史紀錄永遠不變，但使用權可能之後被撤銷、到期，屆時查得到「當初為什麼准了」，也查得到「現在為什麼不能用了」。

為什麼「註冊成功」不等於「能呼叫 API」

圖 1-5 從註冊到真正呼叫之間要通過三道關卡：①註冊成功→②有沒有核准的使用權（ApiGrant）→③Client 手上的通行證（Token）還有效嗎→④呼叫的當下這一切是不是都還有效→通過才會⑤真的打到上游服務。任何一關回答「否」，呼叫就在那裡被擋下並留下拒絕紀錄。

驗收金句：「註冊只證明『你是誰』，不證明『你能用什麼』。要經過使用申請、管理者核准並建立使用權，而且每一次呼叫當下，使用權、通行證、會員與服務的狀態都還有效，才能真的打到上游。」

這 30 小時只做一條完整流程，範圍要鎖死

30 小時做不完全部功能，所以大綱刻意收斂：只做「會員前臺＋管理後臺＋一個平台 API＋MCP 伺服器」全部放在同一個網站；服務只支援受控的 GET／POST，且要有明確規格；一支服務可以有多個版本，申請與授權都綁死某個版本。不做多租戶、不做讓使用者上傳任意程式、不做金流計價、也不保證能接任何商用 AI 助理。

「版本鎖定」則是指開課第一天就把 .NET SDK、套件版本、MCP 協定版本全部寫死，全班用同一版，避免老師電腦能跑、學生電腦編譯失敗卻查不出是版本問題。

老師示範做了什麼

示範情境：同時啟動「網站」跟「示範用的上游 API」，打開環境檢查頁，證明網站能跑、資料庫能連、兩支唯讀服務打得通；再故意停掉上游 API，讓大家看到失敗時畫面長什麼樣。

圖 1-6 環境檢查頁：SQL Server 顯示已連線（系統資料庫還沒建立是正常的，下一章才會建），商品查詢和課程查詢兩支唯讀服務都顯示 HTTP 200 正常；服務工單建立那支因為是「寫入型」，這裡只列出、不會自動呼叫。

圖 1-7 把示範 API 關掉之後重新檢查：SQL Server 那一塊仍然正常（兩項檢查互不影響），但兩支唯讀服務都變成紅色的「失敗」，訊息說明是連線逾時；服務工單那支仍然是「未呼叫」不受影響。

老師特別提醒兩個重點：①「連線逾時」訊息不是隨便編的，是用 3 秒逾時去偵測，失敗大概等 3 秒才顯示；②「服務工單建立」是寫入型的服務，設計上這個檢查頁永遠不會主動呼叫它，避免每次重新整理都真的建立一張工單。

自己動手的步驟

步驟一：建立 Solution 並鎖定版本

用指令建立一個叫 McpPlatform 的方案，裡面放「網站」跟「示範用的上游 API」兩個專案，同時把 .NET SDK 版本寫進 global.json 鎖死：

dotnet new globaljson --sdk-version 10.0.401 --roll-forward latestPatch
dotnet new sln -n McpPlatform
dotnet new mvc -n McpPlatform.Web -o src/McpPlatform.Web
dotnet new web -n McpPlatform.DemoApis -o src/McpPlatform.DemoApis
dotnet sln add src/McpPlatform.Web src/McpPlatform.DemoApis

接著建一個 Directory.Packages.props 檔案，把「整個方案共用的套件版本」集中寫在這一個地方，之後每個專案的檔案裡就不必再各自寫版本號——這樣以後升級套件只要改一處。跑一次 dotnet build，看到「0 個錯誤」就對了。

步驟二：固定埠號，啟動網站

預設的埠號是隨機的，改成網站固定用 5199、示範服務固定用 5080，全班網址才會一致。改完啟動網站，打開「環境檢查」頁，這時候 SQL Server 那格會先顯示紅字的登入失敗——這是預期中的，因為密碼還沒設定，下一步就會修好。

步驟三：把資料庫密碼放進安全的地方

連線字串裡的真實密碼不會寫進程式碼或設定檔（那些檔案會進版本控制、被所有人看到），而是用 .NET 內建的「User Secrets」機制存在自己電腦的一個獨立位置：

dotnet user-secrets init --project src/McpPlatform.Web
dotnet user-secrets set "ConnectionStrings:DefaultConnection"   "Server=localhost;Database=MCPServerManag;User Id=sa;Password=<你的密碼>;TrustServerCertificate=True"   --project src/McpPlatform.Web

設定好、重新啟動網站後，環境檢查頁的 SQL Server 應該顯示「已連線；系統資料庫尚未建立」——資料庫本身要到下一章才會真正建出來，現在看到「尚未建立」才是對的結果。

步驟四：列出三支示範服務的呼叫清單

把「商品查詢」「課程查詢」「服務工單建立」三支示範服務的呼叫方式整理成兩份清單：一份是給人手動測試用的文字檔，一份是給網站程式讀取的設定。其中「服務工單建立」是會寫入資料的服務，特別多兩道保護：一定要帶一個「防重複鍵」（同一把鍵重送不會建立第二張工單），而且一定要明確帶上「已確認」的旗標才會真的建立，這也是將來 AI 呼叫這類服務時「先問過使用者、確認後才動手」的依據。

常見錯誤

症狀	原因	怎麼處理
環境檢查頁：SQL 登入失敗	密碼還沒設定，或設定完沒重啟網站	重新跑一次設定密碼的指令，並且務必重新啟動網站
環境檢查頁：兩支唯讀服務連線逾時	示範上游 API 沒有啟動，或埠號兜不起來	另開一個終端機視窗，啟動示範 API 專案，確認埠號一致
啟動時說埠號已經被佔用	前一次執行的網站沒有關掉	回到那個終端機視窗按停止鍵；找不到就用系統工具找出佔用該埠的程式並結束它
用命令列工具送中文參數卻收到編碼錯誤	某些命令列環境預設不是用 UTF-8 編碼送出中文字	改用 .http 測試檔案，或把要送出的內容存成 UTF-8 檔案再送出

怎麼驗收＋反向驗證

網站可以正常啟動：建置沒有錯誤，啟動示範服務與網站後，環境檢查頁跟本章圖 1-6 一致。
能講清楚「註冊不等於能呼叫」：對著圖 1-5 講出三個重點——註冊只建立會員資料、不會產生使用權；要經過申請與核准才有使用權；有了使用權之後，每一次呼叫當下都還要重新檢查通行證、額度、會員與服務狀態。只講到第一點不算通過。
反向驗證一：故意停掉示範服務再重新檢查，兩支唯讀服務必須變成紅色失敗、但 SQL Server 那格要維持正常——如果整頁一起壞掉或卡住，代表錯誤處理沒寫對。
反向驗證二：呼叫「服務工單建立」時故意不帶「已確認」旗標，必須得到失敗回應，而且不會真的產生新工單。