MCP

MCP（Model Context Protocol）bridge 把 proto 裡標了 gortexa.ai.v1 annotations 的方法暴露成 tools。AI agent 對 /mcp 發 JSON-RPC，bridge 經 in-process gRPC loopback 呼叫原本的服務——AI 的呼叫跟一般請求過同一條攔截器鏈，auth 與 validation 一段不少。

標注方法

在 rpc 上加 gortexa.ai.v1.ai_tool annotation：

rpc GetResource(GetResourceRequest) returns (Resource) {
  option (google.api.http) = {get: "/v1/resources/{id}"};
  option (gortexa.ai.v1.ai_tool) = {
    expose: true
    name: "get_resource"
    description: "Fetch a single resource by id and return its current state."
    read_only: true
  };
}

read_only 與 destructive 會進入 tool schema 的行為提示。沒標 expose: true 的方法不會出現在 tools 清單。

Endpoint

• 路徑：/mcp（Streamable HTTP）
• Protocol versions：2025-03-26（預設）與 2024-11-05
• Request body 上限 1 MB、讀取逾時 30 秒
• Browser-based client 需要 CORS 時開 server.enable_cors，並把允許的 origin 列進 server.cors_origins——這個 allowlist 就是防 DNS rebinding 的機制，沒列的 origin 拿不到 CORS headers

tools/list

curl -XPOST localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

回傳所有標注方法的 tool schema。清單是 memoized 的（約 285 ns 一次），不會每次呼叫重算。

tools/call

tools/call 的參數被序列化成 protobuf 訊息、經 loopback 打到原服務，結果再轉回 JSON-RPC。沒過 auth 就得到 unauthenticated 的 error envelope，跟 gRPC、HTTP 的行為一致。

Schema 匯出

同一份 gortexa.ai.v1 annotations 可以離線輸出成 provider-ready 格式：

gortexa export --format=mcp
gortexa export --format=openai   # OpenAI strict function calling
gortexa export --format=gemini

三種輸出都有 golden test 鎖定：proto 改了，schema 跟著變，測試會抓到意外的漂移。