Skip to main content
The bridge functions (callToolViaGateway and callToolViaGatewayWithAgent, exported from sec0-sdk/middleware) are the client-side interface for routing tool calls through the gateway. They construct the HTTP request with all required headers (auth, trace context, agent state, idempotency key, and AP2 mandates) then forward to the gateway’s POST /mcp/:server/:toolAtVersion endpoint. The gateway validates, enforces policy, and proxies to the upstream tool server, preserving full custody chain continuity.

​
callToolViaGateway (BridgeCallOptions)

KeyTypeRequiredDescription
gatewayBaseUrlstringYesGateway base URL
serverstringYesTool server name
toolAtVersionstringYesTool name@version
argsanyNoTool arguments
authHeaderstringNoAuthorization header (Bearer)
tenantstringNoTenant override
traceparentstringNoW3C traceparent header
baggagestringNoW3C baggage header
runIdstringNoGraph run identifier
nodeIdstringNoGraph node identifier
idempotencySaltstringNoExtra entropy for idempotency key
timeoutMsnumberNoRequest timeout (ms)
ap2.intentstringNoAP2 intent mandate header
ap2.cartstringNoAP2 cart mandate header
ap2.bundlestringNoAP2 bundle header
cause.traceIdstringYesParent trace ID
cause.spanIdstringYesParent span ID
identity.authorizationstringNoDownstream auth context
identity.tenantstringNoTenant claim
identity.rolesstring[]NoRoles claim
identity.userIdstringNoUser ID
identity.userHashstringNoUser hash
identity.assertionstringNoExtra assertion
agentStateobjectNoAgent state payload

​
agentState (AgentStatePayload)

KeyTypeRequiredDescription
nodeIdstringYesNode identifier
runIdstringNoRun identifier
parentRefstringNoParent reference
variablesobjectNoAgent variables by scope
metadataobjectNoArbitrary metadata

​
callToolViaGatewayWithAgent (AgentBridgeCallOptions)

AgentBridgeCallOptions is BridgeCallOptions plus an agent block (and without agentState).

​
agent

KeyTypeRequiredDescription
agent.nodeIdstringYesAgent node ID
agent.runIdstringYesAgent run ID
agent.variablesobjectNoAgent state variables
agent.metadataobjectNoAgent state metadata

​
buildIdempotencyKey

buildIdempotencyKey({
  runId?: string;
  nodeId?: string;
  toolAtVersion: string;
  args?: any;
  salt?: string;
}): string
Returns a composite key built from runId, nodeId, toolAtVersion, and a short digest of args. For deterministic keys, pass stable runId and nodeId values; if runId is omitted, the helper generates one.