MCP

The MCP (Model Context Protocol) bridge exposes proto methods annotated with gortexa.ai.v1 as tools. An AI agent sends JSON-RPC to /mcp, and the bridge calls the original service over an in-process gRPC loopback — so AI calls pass through the same interceptor chain as everything else, auth and validation included.

Annotating methods

Add the gortexa.ai.v1.ai_tool annotation to an rpc:

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 and destructive feed the behaviour hints in the tool schema. Methods without expose: true do not appear in the tools list.

Endpoint

• Path: /mcp (Streamable HTTP)
• Protocol versions: 2025-03-26 (default) and 2024-11-05
• Request bodies capped at 1 MB, read timeout 30 seconds
• For browser-based clients, enable server.enable_cors and list the allowed origins in server.cors_origins — that allowlist is the DNS-rebinding guard; unlisted origins get no CORS headers

tools/list

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

Returns the tool schema for every annotated method. The list is memoized (about 285 ns per call), not recomputed on every request.

tools/call

Arguments to tools/call are serialized into a protobuf message and dispatched to the original service over the loopback; the result is converted back to JSON-RPC. A call that fails auth gets an unauthenticated error envelope, consistent with gRPC and HTTP behaviour.

Schema export

The same gortexa.ai.v1 annotations can be exported offline in provider-ready formats:

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

All three outputs are locked by golden tests: when the proto changes, the schemas change, and unexpected drift fails the tests.