GECX, MCP and companion forms

Status: Current | Last reviewed: 2026-10-08

Use this guide to connect a GECX conversation to the standalone multimodal service and a customer's browser. It covers the deployed Cloud Run pilot, the APIs behind form updates, and the remaining work for ANI and SMS.

Explore the diagrams

Start with the combined architecture. It puts the ANI handoff, GECX, MCP, SMS, mobile browser, public web entry and session stores on one canvas. Numbered connections and the notes below the map explain the request and submission flow. Use its guided views to focus on one part of the same architecture.

Each HTML file contains the diagram and viewer. Open it in a browser to zoom, trace connections, switch themes or export an image.

Diagram	Scope
Combined architecture	Complete connection on one canvas, with deployed pilot components and remaining setup marked
Hosted runtime	GECX, private Cloud Run, catalogues and sidecar stores
Form request and submission	Session binding, MCP calls, SSE rendering and the return of submitted fields
ANI, SMS and mobile access	Target voice integration, the existing AWS SMS code, link redemption and customer access requirements

The diagrams focus on the service and customer integration. Use the Cloud Run runbook for the operator's local test access. Customer browsers need the public HTTPS web entry marked SETUP in the combined architecture.

The Cloud Run pilot passed a native GECX form test on 8 October 2026. An agent resolved the experience, opened the driver form, waited for a synthetic HTTP submission and confirmed the submitted details. The SMS path has code and unit coverage; this deployment has no configured AWS sender or customer web ingress.

Responsibilities

Participant	Responsibility
Call integration or application backend	Start the GECX conversation, supply caller context and keep its session identifiers
GECX agent	Choose tools and interpret their results
GECX MCP client	Authenticate to /mcp, discover tools and execute tools/call
Multimodal service	Validate tool access, resolve the experience, publish form definitions and read submissions
Customer browser	Render supported forms, collect fields and submit an action
Postgres	Hold the experience UUID, catalogue scope, tool scope and expiry
Redis	Hold render streams, surfaces, submitted actions, receipts and SMS connection state

Your agent connects through Streamable HTTP MCP. The browser connects through the service's REST and SSE endpoints. Google's restriction on legacy MCP SSE transport does not prevent the companion page from using SSE.

The standalone service contains no GECX API client. Your integration calls Google's session APIs; Google calls the MCP service. A completed form returns through an outstanding or subsequent MCP tool call.

GECX API calls

The pilot used the REST API on https://ces.googleapis.com with v1beta resource paths. The repository's voice adapter uses Google's v1 WebSocket session endpoint.

In the table, APP means projects/PROJECT/locations/us/apps/APP_ID, SESSION means APP/sessions/SESSION_ID, and TOOLSET means APP/toolsets/TOOLSET_ID.

Caller	API	Purpose and evidence
Operator or provisioning code	POST /v1beta/APP/toolsets	Register the remote MCP URL, authentication and custom headers; used during pilot setup
Operator or provisioning code	POST /v1beta/TOOLSET:retrieveTools	Discover the tools; GECX returned all 12 from this service
Operator or provisioning code	PATCH /v1beta/APP/agents/AGENT_ID?updateMask=toolsets,instruction	Attach selected tools and instructions
Operator or provisioning code	PATCH /v1beta/APP?updateMask=variableDeclarations	Declare the session variables GECX may use
Application backend or simulator	POST /v1beta/SESSION:runSession	Supply variables and a customer turn; verified in the form test
Application backend	POST /v1beta/SESSION:streamRunSession	Google's streaming response API; available in the API definition, outside the pilot test
Voice adapter	WebSocket BidiRunSession	Carry audio and agent responses; implemented in the TrueServe adapter, outside the pilot voice test
Operator test client	POST /v1beta/APP:executeTool	Test one tool; a diagnostic endpoint, not the submission callback

The voice endpoint in the repository is:

wss://ces.googleapis.com/ws/google.cloud.ces.v1.SessionService/BidiRunSession/locations/us

The adapter sends an initial config containing the GECX session resource and audio formats. It then sends realtimeInput messages. It also calls REST runSession with inputs[].variables to bind session context.

The existing adapter starts that REST bind beside its greeting. For a new SMS integration, complete and check the bind before allowing a tool that needs caller context. The pilot verified variables and customer text in one REST request; it did not validate the adapter's event-only bind for this agent.

MCP authentication and session binding

Use the checked toolset configuration. The GECX setting Service Agent ID Token selects the CES service agent:

service-288250959474@gcp-sa-ces.iam.gserviceaccount.com

Google authenticates that identity at Cloud Run ingress. The app verifies the Google signature, issuer, audience, expiry and allowlisted email. The project grants this service agent invocation access, so the pilot needed no new IAM grant.

Bind the declared string variable experienceSessionId to:

X-Trueserve-Session-Id: $context.variables.experienceSessionId

For the operator-created experience, send the variable with the first turn:

{
  "config": {"useToolFakes": false},
  "inputs": [
    {"variables": {"experienceSessionId": "EXPERIENCE_UUID"}},
    {"text": "Please add a driver using the companion form."}
  ]
}

The agent calls get_session_info() without arguments to resolve the header. It then uses the returned session_id as experience_session_id in the auto tools. The runtime uses initialize, notifications/initialized, tools/list and tools/call over /mcp; these are MCP methods.

Keep these values separate:

Value	Owner and purpose
GECX session resource	Your integration chooses a Google conversation identifier
Experience UUID	Multimodal issues the ID for one companion experience
MCP transport session ID	The MCP implementation manages protocol state
surface_id	The auto tools use auto-driver or auto-vehicle inside an experience
connectionRequestId	Your backend generates a stable deduplication key for SMS connection attempts
ANI / callerPhone	Your call integration supplies a phone number

ANI from the call to the SMS tool

Your telephony or CCaaS integration must capture ANI from that channel's call metadata. The MCP service has no telephony connection and receives no ANI unless the caller passes it as a tool argument.

The TrueServe pipeline supports this authored GECX variable mapping:

{
  "input_variables": {
    "callerPhone": "$var:ani",
    "connectionRequestId": "$var:connection_request_id"
  }
}

callerPhone and connectionRequestId are proposed names for this integration. Declare them as strings in the GECX app. TrueServe resolves $var:ani from runtime metadata/session variables. Your backend must add connection_request_id; the existing wrapper does not generate an SMS key. Use a stable value such as a server-generated UUID without hyphens and reuse it for retries of that connection attempt.

A custom adapter can supply the resolved values through inputs[].variables without running TrueServe. Bind the declared variables into the agent's tool instructions or argument configuration; declaring a variable alone does not populate a tool argument. The intended call is:

{
  "name": "connect_auto_experience",
  "arguments": {
    "phone_number": "+12025550123",
    "request_id": "0123456789abcdef0123456789abcdef",
    "send_link": true
  }
}

The phone number and request key above are examples. Read the real values from trusted session context. The service accepts E.164 numbers and common US national formats; strip a provider's tel: prefix in the adapter. ANI may be absent or refer to a number that cannot receive SMS. Ask the customer for a mobile number in that case. ANI does not authenticate the customer.

SMS connection and mobile access

The connection implementation uses AWS End User Messaging SMS. Its SDK client name is pinpoint-sms-voice-v2; its operation is SendTextMessage.

1. GECX calls connect_auto_experience with the phone number and stable request key. Omit experience_session_id to let this tool create a new experience.
2. The service creates an acg-auto experience with the four auto tools. It stores an opaque share-code hash in Redis and creates https://BROWSER_HOST/demo/#connect=CODE.
3. The service calls AWS with DestinationPhoneNumber, OriginationIdentity, the link in MessageBody, MessageType: TRANSACTIONAL and TimeToLive: 300.
4. AWS returns a MessageId. The tool reports sms_submitted, the experience ID and a masked recipient. Carrier delivery and the customer's link opening happen after that acceptance.
5. The customer opens the link. The page removes the URL fragment from browser history, posts the code to /v1/connections/redeem, and keeps the returned experience JWT in memory.
6. The browser opens /v1/sessions/{id}/events with that JWT. The service records a short-lived connection marker while servicing the stream.

The link expires with the experience. The implementation permits redemption again until expiry; it does not consume the code on the first visit. The tool's connected field reflects a recent SSE connection.

After connect_auto_experience, reuse its returned experience ID in later tool arguments. An MCP result does not assign a GECX session variable. This SMS bootstrap grants the auto tools; the operator pilot instead creates an experience with generic catalogue tools and excludes the connection tool. Do not reuse that pilot experience for SMS without changing its tool scope.

The service stores the connection attempt before calling AWS. It returns the stored result for a matching retry, rejects changed inputs under the same request key and avoids an automatic second send after an ambiguous AWS result. The code also caps sends at five per recipient per hour.

Form updates and submitted fields

start_auto_change chooses the session's insurance catalogue and emits createSurface and updateComponents. The service writes render frames to the Redis stream entries:{experience_id}. The edge SSE handler reads that stream. A reconnecting browser supplies lastEventId to resume from its cursor.

Your customer submits or cancels through POST /v1/sessions/{id}/ui-action. The service checks the browser JWT, session, surface and form fields, then writes an action to mm:actions:{id} and a retained result to mm:result:{id}:{surface_id}. A repeated event_id with the same data gets the same acknowledgement; conflicting data returns 409.

GECX calls await_auto_change to read the result. A submission can arrive before the call or while it waits. After 20 seconds without a submission, the tool returns pending; the agent can call again. The standalone service does not call runSession, inject a transcript turn or send a GECX webhook when the customer clicks Submit.

Change	Current behavior
Open an ACG driver or vehicle form	GECX calls an auto tool; the browser renders the SSE frames
Type into the browser form	The page holds those values until Submit
Submit or cancel	The browser posts a ui-action; a wait tool returns it to GECX
Update generic components or a data model	The MCP tools emit A2UI; the consuming application needs a renderer for those operations
Submit spoken details	submit_spoken_auto_change records confirmed details; it does not prefill the open browser fields

The bundled page renders ACG forms and legacy AutoChangeForm, handles updateComponents and deleteSurface, and ignores generic updateDataModel frames. The three loaded catalogues do not imply a browser renderer for each component.

Remaining work for the customer SMS path

Work	Reason
Add the call adapter and declare ANI/request-key variables	The deployed text pilot has no telephony handoff
Configure AWS credentials and an SMS origination identity	The Cloud Run deployment has neither
Add a public HTTPS browser front door	A customer opening the private Cloud Run URL receives 403
Forward browser requests with a Google ingress identity and preserve the browser JWT	Cloud Run IAM and the app's session authorization serve different boundaries
Separate the browser link origin from the MCP origin, or configure both through a reviewed ingress design	MULTIMODAL_PUBLIC_URL controls link generation, MCP Host checks and token audiences/issuer
Attach connect_auto_experience and use its returned experience ID	The pilot configuration excludes SMS and uses a different bootstrap
Test real SMS, mobile reconnection and voice interruption	The verified GECX pilot uses synchronous tool calls and synthetic submissions

The public browser front door needs /demo/ and its assets, connection redemption, session SSE and session action routes. Keep operator POST /v1/sessions and MCP behind their existing authorization. Use the operator's gcloud run services proxy for the private preview.

For production, replace the sidecar Postgres and Redis stores with persistent services. In this sandbox, an instance replacement clears the connection link, experience and submission state.

Evidence and reproduction

The diagrams describe the reviewed working tree and the pilot verification. They do not claim that uncommitted files match a published repository revision.

Source	What it establishes
Cloud Run manifest and runbook	Private ingress, sidecars, embedded catalogues and pilot test results
MCP auth, tool session resolver	Signed Google identity, experience ID and tool-scope checks
Auto tools and connection code	Tool arguments, SMS API, deduplication, link generation and redemption
Renderer, edge API, action store	Render streams, SSE, action validation and retained submissions
Browser adapter	Fragment removal, token storage, renderer limits, form submit and reconnect behavior
Variable resolution and GECX wrapper	ANI mapping support and provider context
GECX transport	WebSocket endpoint and REST session-variable bind

Vendor references, checked on 8 October 2026:

• Google MCP tools
• Google CES v1beta API definition
• Google private Cloud Run authentication
• AWS SendTextMessage API

The verification record records source digests, specification and HTML receipts, automated checks and visual review. Each diagram has its typed JSON specification beside the HTML.

See also

• GECX agent setup
• Cloud Run operations
• Multimodal service