---
title: "Appendix: Tool Gateway Protocol"
framework: Private Cloud Compute Security Guide
role: article
role_heading: Article
path: private-cloud-compute/appendix_toolcalling
---

# Appendix: Tool Gateway Protocol

The wire formats and connection life cycle used in PCC’s tool-calling flow.

## Overview

Overview The External tool calls provides a protocol similar to Model Context Protocol (MCP), using JSON-RPC messages with an MCP-like shape and carrying those messages over a gRPC bidirectional stream. Connection life cycle An external tool call follows three phases: gRPC service The PccToolGateway gRPC service defines the wire format: service PccToolGateway {     rpc CreateMcpTransport(stream CreateMcpTransportRequest)         returns (stream CreateMcpTransportResponse); }

message CreateMcpTransportRequest {     message Connect {         string server_id = 1;         reserved 2, 3, 4;         string request_id = 5;         TraceContext trace_context = 6;         TenantInfo tenant_info = 7;         string server_cloudos_version = 8;     }     oneof request {         Connect connect = 1;         string request_body = 2;  // tool call JSON-RPC message     } }

message CreateMcpTransportResponse {     message Connected {     }     oneof response {         Connected connected = 1;         string json = 2;     } } CreateMcpTransport is a bidirectional streaming RPC. Both request and response messages use a oneof field that carries either a connection-management message or a JSON string that contains a JSON-RPC message. In addition to the target server_id, the Connect message carries the request’s request_id and a trace_context. Its trace ID is the same one propagated across PCC nodes for this request, so the calls belonging to one request are correlatable; its span ID is minted per tool call on the node. The Connect message also carries a tenant_info record that identifies the application and feature that originated the user’s request, not the cloud application that performs the tool call. The record contains the bundle identifier, the feature identifier, the client-info string reporting the device model and operating system version, and the automated-test device group. This is the same unencrypted request metadata available to other components outside the trust boundary, and like that metadata, it carries no information identifying the source device or user. The final field, server_cloudos_version, reports the operating system version of the node making the call; that version is common to every node running the release. Message format The messages exchanged with the tool gateway — initialize, notifications/initialized, and tools/call — are standard JSON-RPC messages carried as strings in the request_body field of CreateMcpTransportRequest (and the json field of CreateMcpTransportResponse). The id field on a tools/call request is the tool-invocation identifier, which is distinct from the PCC request identifier the Connect message carries; cb_bridged mints it per tool call and also sends it as the stream’s Apple-Request-UUID header. The initialize request has an id of its own. As a JSON-RPC notification, notifications/initialized has no id field. A tool-call request takes the following form: {     "jsonrpc": "2.0",     "id": "<tool-invocation-id>",     "method": "tools/call",     "params": {         "name": "<tool-name>",         "arguments": { ... }     } } The tool gateway returns a response that contains the tool’s output: {     "jsonrpc": "2.0",     "id": "<tool-invocation-id>",     "result": {         "content": [             {                 "type": "text",                 "text": "<tool output>"             }         ],         "structuredContent": { ... },         "isError": false     } } The content array supports multiple types: text, image, audio, and resource. A successful response carries its result payload in the structuredContent and content fields. structuredContent is a typed JSON object that cb_bridged parses; PCC treats structuredContent as the authoritative payload and rejects any tool response that omits it. The tool gateway signals failures in one of two ways: A JSON-RPC protocol-level error, such as an unknown method or a malformed request, returns a top-level error object with a numeric code and a message in place of result. A tool-execution error, where the tool ran but failed, returns a normal result with isError set to true; the failure detail is carried in the content array, typically as text. The Appendix: TIE Response Protocol is distinct from the tool gateway protocol. A Shadow Tunneling stands in for TIECloudApp in the VRE, and the TIE response protocol is a stripped-down version of TIECloudApp’s own inference-response protocol. This minimal protocol lets a researcher Exercise external tool calling without running a live model.