Gortexa

Features

Three protocols, one port

h2c multiplexing on Go’s native http.Server.Protocols. One port accepts gRPC, HTTP/JSON and MCP.

Fixed-order interceptor chain

recover → request-id → logger → load-shed → rate-limit → circuit-breaker → auth → validation. Eight stages in a fixed order; a missing stage fails startup.

One error model

A single mapping table produces the gRPC status, HTTP status and MCP error envelope. Internal causes never leak.

AI tool calls go through the same chain

MCP tools/call dispatches over an in-process loopback, so AI calls pass auth and validation like any other request.

Batteries included

Layered config, three-state health, slog + OTLP, pgx + sqlc, cache (in-memory by default), NATS/JetStream.

Importable as a module

go get the framework packages directly — kernel/interceptor/mq for plain services, plus the mcp bridge and gortexa.ai.v1 annotations for AI ones. No scaffold required. See Components.

Get started

To have a coding agent build a runnable service scaffold from a prompt, use Quickstart with AI. It pins the release, verifies the toolchain, confirms the scaffold left the startup-refusing placeholder secret in place, and runs HTTP/MCP smoke checks in one shell. For a manual walkthrough, use Quickstart.

Both paths create a prototype only; see Deployment for the work required before production.

Or consume the framework as a Go module — go get it and import the packages directly, no scaffold required:

go get github.com/yshengliao/gortexa@latest

See Components for each package’s usage, or Use as a module for a minimal app.

After either flow starts the server on :8080, hit each protocol once:

curl localhost:8080/healthz                                # 200: health check is open
curl -XPOST localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'      # MCP: list AI tools defined in proto
curl localhost:8080/v1/resources/x                         # 401: auth is shared across all three

FAQ

What is Gortexa?

A contract-first, batteries-included gRPC framework for Go: Protobuf is the single source of truth, and one h2c port serves gRPC, HTTP/JSON (grpc-gateway) and MCP, all sharing one interceptor chain, one error model and one auth path.

Which Go version does it need?

It targets Go 1.27. Any installed Go 1.21+ works as the bootstrap: GOTOOLCHAIN auto-downloads go1.27.0.

How do three protocols share one port?

Go’s native http.Server.Protocols does the h2c multiplexing; the HTTP gateway and the MCP bridge dial the gRPC server over an in-process loopback, so auth, rate limiting, validation and error mapping are identical across all three.

Do I need Redis or Kafka?

No. The cache defaults to process-local in-memory (redis is opt-in); messaging uses NATS (core, at-most-once) or JetStream (durable, at-least-once) — there is no Kafka dependency.

How do AI agents call my API?

Annotate the proto with gortexa.ai.v1 annotations and the MCP bridge exposes those RPCs as MCP tools; an AI’s tools/call passes the same auth and validation as any human request. See the MCP transport.

How does Gortexa differ from connect-go?

Both multiplex protocols on one port, but different ones: connect-go serves Connect, gRPC and gRPC-Web, while Gortexa serves gRPC, HTTP/JSON (grpc-gateway) and MCP. The differentiating axis is AI — Gortexa exposes annotated RPCs as MCP tools through the same interceptor chain. See the full comparison.

Can I use individual components without the scaffold?

Yes. go get github.com/yshengliao/gortexa and import the public packages — kernel, interceptor, mq, mcp and the rest — individually. See Components.