gRPC Connections

gRPC connections let agents discover and invoke methods on a gRPC, ConnectRPC, or gRPC-Web service. Discovery uses gRPC server reflection, so the connection works with any service that has reflection enabled — no .proto file upload required.

Recommended: Create and manage connections via the web UI at https://ui.cloud.firetiger.com/settings/connections

Connection Parameters

Required Parameters

Parameter	Type	Description
address	string	Target address in host:port format (e.g., api.example.com:443)

Optional Parameters

Parameter	Type	Description	Default
protocol	enum	Wire protocol for invocation — does not affect reflection	GRPC

Protocol values

Value	Use when
GRPC_PROTOCOL_GRPC	Server speaks native gRPC over HTTP/2
GRPC_PROTOCOL_CONNECT	Server is ConnectRPC-only (HTTP/1.1 or HTTP/2)
GRPC_PROTOCOL_GRPCWEB	Server is behind a gRPC-Web proxy or browser-facing

Service discovery always uses native gRPC reflection regardless of this setting — only method invocation honours protocol.

Authentication

Set exactly one. Credentials are injected by the fireshell network proxy and agents never construct the auth header themselves.

Auth injection requires port 443. The fireshell HTTPS proxy (TPROXY) only intercepts traffic on port 443, so credentials are only attached when address ends in :443. For any other port (e.g. :8443, :50051), requests go through unauthenticated and the server typically rejects them. Front non-443 gRPC services with a TLS terminator on port 443, or pick a different connection type.

Bearer Token

"bearer_auth": { "token": "<token>" }

Basic Auth

"basic_auth": { "username": "user", "password": "pass" }

Tools

Tool	Description
grpc_services	List all gRPC services and methods exposed via reflection
grpc_describe	Describe a service or method schema (field types and documentation)
grpc_request	Invoke a method with a JSON payload

The typical agent flow is grpc_services → grpc_describe for the method of interest → grpc_request with the JSON payload.

Example Connection

{
  "display_name": "Internal gRPC API",
  "description": "Internal gRPC API for the orders service. Useful methods:\n- orders.v1.Orders/GetOrder — fetch an order by ID\n- orders.v1.Orders/ListOrders — paged list, filter by status",
  "connection_details": {
    "grpc": {
      "address": "orders-api.internal:443",
      "protocol": "GRPC_PROTOCOL_GRPC",
      "bearer_auth": { "token": "<token>" }
    }
  }
}

Best Practices

• Enable reflection on the server — without it, grpc_services and grpc_describe can’t enumerate methods
• Document the most useful methods in the description so agents don’t have to walk the entire service surface to find them
• Use a service-account credential, not a personal token — agent traffic should be attributable to a long-lived identity