# HTTP 與 MCP

Source: https://gortexa.sheng.page/components/http-mcp/

`httpcompat` 與 `mcp` 是接在同一個 h2c 埠上的兩個非 gRPC 表面：httpcompat 用 grpc-gateway 產生 HTTP/JSON，mcp 把標注過的 RPC 開成 AI agent 可呼叫的 MCP tools。兩者都經 in-process loopback 回撥 gRPC server，因此共用同一條攔截器鏈。

先取得模組：`go get github.com/yshengliao/gortexa@v0.28.3`。以下片段皆對 v0.28.3 編譯驗證過。

## httpcompat

建立 error handler 走 `apperr`、含 protojson marshaler、並把 `Authorization` 與 `X-Request-Id` 轉送到固定 metadata key 的 ServeMux；撞上受信 key（含 peer-IP）的 `Grpc-Metadata-*` 拼法一律拒絕。

```go
import (
	"github.com/yshengliao/gortexa/apperr"
	"github.com/yshengliao/gortexa/httpcompat"
)

gateway := httpcompat.NewServeMux(apperr.Default)
// 把 grpc-gateway handler 註冊到 gateway + loopback conn
handler := httpcompat.MaxBodyBytes(gateway) // body 上限 1 MiB
handler = httpcompat.CORS(handler, cfg.Server)
```

另有 `OpenAPIRoute(next, cfg, specPath)` 掛 OpenAPI spec。

## mcp

把有 `gortexa.ai.v1` annotations 的 RPC 暴露成 MCP tools，經 loopback 過同一條攔截器鏈。

```go
import (
	"github.com/yshengliao/gortexa/apperr"
	"github.com/yshengliao/gortexa/mcp"
)

descs, err := mcp.ServiceDescriptors("resource.v1.ResourceService")
if err != nil {
	return err
}
bridge, err := mcp.NewBridge(conn, descs, apperr.Default, cfg.Observ)
if err != nil {
	return err
}
bridge.SetAllowedOrigins(cfg.Server.CORSOrigins)
app.SetMCPHandler(bridge.Handler())
```

離線輸出 tool schema 用 `mcp.ExportSchemas(format, descs)`，format 為 `mcp`／`openai`／`gemini`。

## 延伸閱讀

- [HTTP/JSON transport](https://gortexa.sheng.page/transports/http-json/)：gateway 的路由、headers 與限制
- [MCP transport](https://gortexa.sheng.page/transports/mcp/)：endpoint 行為與 AI tool schema
- [核心概念](https://gortexa.sheng.page/concepts/)：單埠多工與共用的攔截器鏈