Skip to content

gRPC binding reference

Surface Contract
New(opts...) Builds the part every bound method of one service shares. Options: WithAuthorize(authn.AuthorizeFunc), WithInterceptors(...transitgrpc.Interceptor) (unary halves only, appended in order), WithLogger. Nil or repeated options fail; WithInterceptors may repeat.
Unary[Req, Resp](service, fullMethod, call, opts...) Binds /package.Service/Method, implemented by call func(context.Context, Req) (Resp, error), as an mcp.Operation. Refused when the name is malformed, unregistered or streaming, or Req/Resp are not the method's messages.
Method options WithName, WithGroup, WithSummary, WithDescription, WithHints, WithInputSchema, WithOutputSchema, WithTimeout (positive). Each at most once.
DefaultTimeout 30 seconds.

What a call establishes

The invocation's context, which the server adapter binds to the HTTP request and to shutdown, gains in this order: authn.RequestMetadata{Method: "grpc", Path: fullMethod}, then the *authn.Identity the host's middleware verified, then a deadline of the method's budget unless an earlier one is present, then a span named by the full method (rpc.system=grpc, rpc.service, rpc.method, kind internal) whose parent is the span on the context, from that span's provider or the global one. No identity fails as unavailable before any of this; the predicate's false fails as unavailable after it. Interceptors then run first outermost with UnaryServerInfo{FullMethod}, and the method last.

The binding owns no goroutine, listener or execution slot. There is nothing to register with controls; the invocation's cancellation is the call's.

Wire shapes

Direction Encoding
Arguments protojson.Unmarshal into a fresh request message; unknown fields refused as invalid_arguments.
Result protojson.Marshal of the response as the structured value, with the core's compatibility text.

Derived schemas

Descriptor Input schema Output schema
bool boolean same
32-bit integers integer same
64-bit integers integer string
float, double number same
string string same
bytes string, contentEncoding: base64 same
enum string with enum of value names same
repeated array of the element same
map object with additionalProperties of the value same
message object with properties by JSON name, additionalProperties: false; a message that contains itself is an open object one level down same
Timestamp, Duration, FieldMask string same
Struct, Any, Empty object same
ListValue array same
Value unconstrained same
wrappers the scalar in a type union with null 64-bit wrappers become string

Proto3 fields are all optional, so no derived schema lists required.

Statuses to failures

gRPC status Failure code Message
InvalidArgument, FailedPrecondition, OutOfRange, NotFound, AlreadyExists invalid_arguments the status message
Unauthenticated, PermissionDenied, Unimplemented unavailable fixed
DeadlineExceeded timeout fixed
Canceled cancelled fixed
ResourceExhausted, Unavailable busy fixed
any other status, or a plain error internal fixed
context.DeadlineExceeded, context.Canceled returned as errors timeout, cancelled fixed
an *mcp.Failure passes through unchanged
a nil response with a nil error invalid_result fixed

The original error is the failure's private cause. Failure codes lists what each code means to a caller.

Dependencies

google.golang.org/grpc 1.83.1, google.golang.org/protobuf 1.36.11 (encoding/protojson, reflect/protoreflect), go/authn, go/transit/grpc and go.opentelemetry.io/otel 1.45.0. The root package imports none of them.