MCP

MCP教學：使用2026-07-28規範從零到生產伺服器

作者：IdeaBosque最後更新：2026年8月22日

關鍵要點

MCP SDK月下載量超過9700万，但僅8.5%的伺服器使用OAuth — 協定的采用速度超過了其安全態勢，使本教學中的生產強化步驟对任何B2B部署都不可或缺。
MCP SDK v2将包體積缩减83%，速度提升25% — 2026-07-28規範與重新設計的TypeScript、Python、Go和C# SDK一同發布，每个都有遷移指南。
2026-07-28規範移除了工作階段和初始化握手 — 每个請求现在都是自包含的，可落在普通輪詢負載均衡器後的任何伺服器實例上，無需共用狀態。
8月22日MCP路線圖定義了五个優先領域 — 代理身分、HTTP傳輸統一、代理訊息原語、改進的工具原語和SDK開發者體驗 — 本教學的生產路徑涵蓋了每一项。
82%的MCP伺服器存在路徑遍历漏洞（据Practical DevSecOps） — 此处的沙箱化和輸入驗證步驟是演示與部署之間的区别。

Model Context Protocol在2026年突破了9700万月SDK下載量，TypeScript和Python SDK各自超過10亿总下載量。2026-07-28規範發布了自推出以来的最大修订：無狀態協定核心、一等擴充和三个简化部署面的棄用。三周後，8月22日，MCP维护者發布了新路線圖，定義了下一規範週期的五个優先領域 — 代理身分、HTTP傳輸統一、代理訊息原語、改進的工具原語和SDK開發者體驗。

本教學涵蓋生產路徑：建構一个無狀態、水平可擴充、身分感知且为路線圖企業優先級做好准备的MCP伺服器。官方快速入門講解了一个連線Claude Desktop的天气伺服器。本文从该快速入門结束的地方开始 — 从可執行的演示到你会放在B2B代理系統背後的生產伺服器之間的步驟。

第1步 — 使用SDK v2进行專案設定

2026-07-28規範與重新設計的SDK一同發布。TypeScript SDK v2透過新的客戶端-伺服器拆分，将包體積缩减约83%，性能提升25%。Python SDK 2.0+、Go SDK和C# SDK v2.0在發布日均支援2026-07-28協定版本，并有针对破壞性變更的詳細遷移說明。

本教學使用Python 3.10+和uv：

uv init mcp-server
cd mcp-server
uv venv
source .venv/bin/activate
uv add "mcp[cli]"

mcp[cli]额外包带来了執行和檢查伺服器的CLI工具。SDK使用Python類型提示和檔案字串自動產生工具定義 — 你定義一个函数，裝飾它，協定元資料就从簽章中衍生出来。

第2步 — 定義你的第一批工具

MCP伺服器暴露三种能力類型：tools（模型呼叫的函数）、resources（模型读取的資料）和prompts（範本化工作流）。对于B2B伺服器，tools是主要介面 — 代理如何搜尋目錄、產生報價或保留庫存。

from mcp.server import MCPServer

mcp = MCPServer("catalog-server")

@mcp.tool()
async def search_catalog(query: str, supplier_id: str | None = None) -> str:
    """Search the supplier catalog by keyword, optionally filtered by supplier.

    Args:
        query: Search keyword (SKU, product name, or category)
        supplier_id: Optional supplier filter (e.g., "s-12")
    """
    results = await catalog.search(query=query, supplier_id=supplier_id)
    return format_results(results)

@mcp.tool()
async def get_pricing(sku: str, quantity: int) -> str:
    """Get tiered pricing for a SKU at a given quantity.

    Args:
        sku: Supplier product identifier
        quantity: Order quantity (determines pricing tier)
    """
    price = await pricing_engine.get(sku=sku, quantity=quantity)
    return f"SKU {sku}: ${price.unit_price:.2f} (tier: {price.tier_name})"

每个工具的檔案字串成为模型在其工具列表中看到的描述。類型提示成为輸入模式。这是MCP Module Code Standard模式：每个工具都有類型化模式、清晰的檔案字串和單一職責。

**STDIO日誌陷阱：**对于基於STDIO的伺服器，切勿寫入stdout — 它会破壞JSON-RPC訊息流。使用標準logging模組，它寫入stderr：

import logging
logger = logging.getLogger(__name__)
logger.info("Catalog search: query=%s", query)  # stderr, safe

第3步 — 傳輸：STDIO vs Streamable HTTP

2026-07-28規範使遠端MCP伺服器"與任何其他HTTP工作負載无异"（規範變更日誌）。路線圖的第二个優先領域 — HTTP原生傳輸統一 — 将此擴充到透過stdio说Streamable HTTP的本地伺服器，統一为一种傳輸模型。

对于本地开发和桌面客戶端，STDIO是默认选项：

if __name__ == "__main__":
    mcp.run(transport="stdio")

对于生產B2B部署 — 代理作为云工作負載執行，而非桌面應用 — Streamable HTTP是生產傳輸。伺服器在負載均衡器後執行，接受带有Mcp-Method和Mcp-Name標頭的HTTP POST請求，并透過HTTP回覆JSON-RPC：

if __name__ == "__main__":
    mcp.run(transport="http", host="0.0.0.0", port=8080)

基於標頭的路由功能意味着你的閘道、限流器或WAF可以直接在Mcp-Method和Mcp-Name標頭上进行路由和计量 — 路由決策無需解析JSON正文。这就是無狀態協定設計的部署形態：輪詢負載均衡器後的無狀態伺服器實例池，无共用工作階段层。

第4步 — 有狀態工作流的顯式控制代碼

無狀態并不意味着狀態消失。2026-07-28規範用顯式控制代碼模式取代了隱藏的工作階段狀態：工具建立一个控制代碼（order_id、quote_id、basket_id），模型在後續呼叫中将其作为普通參數傳回。这在MCP 2026-07-28：無狀態協定对B2B代理部署的意义中有詳細講解。

对于跨越五次工具呼叫的報價工作流 — 建立請求、搜尋目錄、產生報價、保留可用性、應用定價层級 — 控制代碼貫穿每次呼叫：

@mcp.tool()
async def create_request(buyer_id: str, line_items: list[dict]) -> str:
    """Create an RFQ request and return a request_id handle."""
    request = await rfq_engine.create(buyer_id, line_items)
    return f"request_id={request.id}"

@mcp.tool()
async def generate_quote(request_id: str, supplier_ids: list[str]) -> str:
    """Generate a quote from specified suppliers. Returns quote_id."""
    quote = await rfq_engine.quote(request_id, supplier_ids)
    return f"quote_id={quote.id}"

每次呼叫攜帶它需要的控制代碼。没有伺服器在呼叫之間記住任何东西。如果負載均衡器将呼叫4路由到與呼叫3不同的實例，它仍然有效 — 控制代碼在請求中。如果稽核團隊一週後需要重建此工作流，請求參數中的控制代碼講述了完整的故事。

第5步 — 代理身分：企業缺口

路線圖的第三个優先領域 — 代理身分和企業級安全 — 对B2B部署最为重要。路線圖明確指出：MCP授權今天"圍繞在瀏覽器中批准存取的人建構"，但"越來越多的呼叫者是作为云工作負載執行的代理，擁有自己的身分，代表不在場的使用者行事，或向子代理委派更窄的權限。"

路線圖定義的前進路徑：

DPoP (RFC 9449) — Demonstrating Proof of Possession将OAuth權杖綁定到客戶端持有的金鑰。僅凭被盜權杖无法从另一个行程重放請求。DPoP不决定代理被允许做什麼；它使憑證更难在其預期持有者之外被重用。
Workload Identity Federation — IETF WIMSE工作组正在开发多系統環境中的工作負載身分架構。代理是工作負載，因此獲得工作負載身分：以SPIFFE ID命名，用短期憑證認證，而非共用API金鑰。
Enterprise-Managed Authorization (EMA) — EMA擴充将存取決策移至組織的身分供應商。MCP客戶端将使用者身分斷言交換为Identity Assertion JWT Authorization Grant (ID-JAG)，然後将该授權交換为伺服器特定的存取權杖。这支援集中分配和撤銷。

对于本教學的生產伺服器，最低基線是：

**无共用API金鑰。**每个代理獲得短期、綁定受眾的權杖。
OAuth with DPoP。Practical DevSecOps MCP Security Statistics 2026報告發現僅8.5%的MCP伺服器使用OAuth — 其余91.5%依賴API金鑰或完全无認證。
每个信任邊界的權杖交換。CoSAI權杖交換標準（8月18日發布）将權杖交換確立为代理工作流的基礎控制。每个register_tools()入口点应接受任務範圍的權杖，而非持久憑證。

參見MCP Security Hardening Checklist了解在生產前驗證这些標準的12项控制，以及MCP Module Code Standard了解模組級防禦態勢。

第6步 — 漸進式工具發現：解決百工具問題

路線圖的第四个優先領域 — 改進的原語 — 解決了一个具體的生產問題："連線到有百个工具的伺服器意味着模型在使用者提出任何問題之前就要为整個表面付費，而且工具選擇隨著列表增長而變差。"

路線圖的答案是漸進式發現：伺服器提供小入口点，隨著對話縮窄而展示更多目錄。伺服器不再在連線时将100个工具模式倒入模型的上下文視窗，而是暴露少量頂層工具，并根據代理正在做什麼動態擴充表面。

2026-07-28規範已提供建構區塊：

server/discover RPC — 客戶端可以在做任何其他事情之前了解伺服器的能力，無需工作階段握手。
tools/list with ttlMs and cacheScope — 列表回應攜帶快取提示，因此客戶端快取工具目錄并避免每次連線时重新取得。
每个請求的_meta — 協定版本、客戶端資訊和能力按請求傳輸，而非在協商的工作階段中。

对于有50+工具的伺服器，漸進式發現模式如下：

@mcp.tool()
async def discover_tools(category: str) -> str:
    """Discover available tools in a category. Start here for a guided tour.

    Args:
        category: Tool category — 'catalog', 'pricing', 'inventory', 'orders'
    """
    available = tool_registry.by_category(category)
    return format_tool_list(available)

代理首先呼叫discover_tools("catalog")，獲得5-8个聚焦工具的集合，僅在工作流需要时才擴充到其他類別。这保持上下文視窗精簡和工具選擇準確 — MCP Module Code Standard單一職責工具設計背後的同一原則。

第7步 — 部署：無狀態、水平、在負載均衡器後

2026-07-28規範設計的部署形態：

                    ┌──────────────────┐
                    │  Load Balancer   │
                    │  (round-robin)   │
                    └────────┬─────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
     ┌────────┴────┐ ┌───────┴────┐ ┌───────┴────┐
     │ MCP Server  │ │ MCP Server  │ │ MCP Server  │
     │  Instance 1 │ │  Instance 2 │ │  Instance 3 │
     │ (stateless) │ │ (stateless) │ │ (stateless) │
     └─────────────┘ └─────────────┘ └─────────────┘
              │              │              │
              └──────────────┼──────────────┘
                             │
                    ┌────────┴─────────┐
                    │  Upstream Systems │
                    │  (NetSuite, etc.)  │
                    └──────────────────┘

无共用工作階段儲存。无黏性工作階段負載均衡器。无工作階段重放基礎设施。每个請求攜帶它所需的一切 — 協定版本、客戶端資訊、能力和控制代碼 — 在請求正文和標頭中，而非伺服器端狀態中。

对于生產強化：

沙箱化每个伺服器實例。MCP Project Sandboxing Baseline（8月16日發布）要求產生行程的OS級沙箱化。使用Landlock (Linux)、Seatbelt (macOS)或Windows ACL来限制檔案系統和網路存取。82%的路徑遍历漏洞率（据Practical DevSecOps）是僅靠輸入驗證不夠的證據。
限制每个工具的速率。MCP Module Code Standard要求每工具速率限制。MCP Ruby SDK DoS漏洞（8月16日揭露）確認資源耗盡攻擊是真實的攻擊面。
**記錄到OpenTelemetry，而非MCP日誌通道。**2026-07-28規範棄用了日誌功能，轉而支援stderr和OpenTelemetry。MCP伺服器日誌與現有可觀測性管道（Datadog、CloudWatch、Honeycomb）整合，無需自定義傳輸。
使用基於標頭的路由进行WAF和限流。Mcp-Method和Mcp-Name標頭让你的閘道在不解析JSON正文的情况下进行路由和授權。

路線圖展望：五个優先領域

8月22日路線圖定義了下一規範週期的方向。本教學涵蓋生產就緒部分；路線圖指出了接下來的內容：

優先領域	狀態	教學覆蓋
代理身分和企業級安全	進行中 (DPoP, WIMSE, EMA)	第5步 — 基線已建立；完整實作待規範定稿
HTTP原生傳輸統一	已發布(遠端)，進行中(本地)	第3步 — 遠端HTTP为生產；本地Streamable HTTP over stdio为路線圖目標
代理訊息原語	擴充發布中 (Tasks, 訂閱)	未覆蓋 — 伺服器發起事件 (webhooks, channels) 为下一前沿
改進的原語(漸進式發現)	設計階段	第6步 — 模式今天可用`discover_tools`實作；規範級支援即將到來
改進的SDK開發者體驗	已發布 (SDK v2, 一致性測試)	第1步 — SDK v2为目前生產基線

路線圖是方向，而非相容性承諾。7月28日規範已交付無狀態HTTP核心和Tasks擴充。推送事件、統一發現、委派和跨SDK一致性仍需實作工作。对于B2B部署，代理身分優先級是值得關注的 — 它解決了MCP安全文章和治理檢查清單一直在指出的确切缺口（API金鑰和長期權杖）。

教學的生產路徑涵蓋五步生產檢查清單：

建構小故事

一家執行NetSuite的中型經銷商想給銷售團隊一个AI助手，可以搜尋供應商目錄、產生報價和檢查庫存水平，而無需離開CRM。第一次嘗試使用了在所有代理實例間共用的單個API金鑰 — 91.5%跳過OAuth的MCP伺服器。供應商價格表更新在日誌檔案中暴露了金鑰，團隊花了兩天時間在15个服務中輪換憑證。

重建遵循本教學的生產路徑：SDK v2 with類型化工具模式、輪詢負載均衡器後的Streamable HTTP傳輸、15分鐘過期的DPoP綁定OAuth權杖、五步報價工作流的顯式控制代碼以及每个伺服器實例的OS級沙箱化。代理透過遵循程式碼標準的MCP模組連線到NetSuite，漸進式發現首先暴露8个目錄工具，僅在工作流需要时才擴充到定價和庫存。六個伺服器實例在負載均衡器後無狀態執行。无共用工作階段儲存。无黏性工作階段。每个請求攜帶其控制代碼、權杖和協定版本。

請求範圍明確的建構

一週發現。你獲得系統清單、工作流地圖和固定範圍 — 無論你是否與我们合作建構。

想為您的系統建構這個嗎？

這裡的每份文件都來自真實的生產工作。如果您有目標系統和工作流程想法，我們可以在一週內確定範圍。

申請客製開發

為期一週的發掘階段。您會拿到系統清單、工作流程地圖和固定範圍——無論您最終是否與我們合作開發。