Connect a host
Use the Relay service origin and scoped bearer credential supplied to your server-side integration. The website is documentation, not an API endpoint. Keep the credential in a secret store. Never include it in prompts, browser code, URL query strings, logs or downloadable configuration.
Connect with MCP Streamable HTTP at /mcp/{connector}. Shopping also supports /mcp. Send the bearer credential in the Authorization header. Initialize the MCP connection, call tools/list, then invoke only the tool names returned for that connector. Read isError and structuredContent before rendering a tool response.
Select only the connectors granted to the host. A connector installation report does not grant permissions. Authentication for an end user on a provider site stays with that provider or the assistant's approved environment. Relay's host connection currently uses a server-side bearer credential; do not assume that an OAuth login flow is available.
Report the installed connectors
Assign an opaque session ID to the host conversation. Do not put an email address or account name in that ID. Report the connectors actually installed and enabled in the host through POST /v1/session/connectors, using session_id, installed_connectors, enabled_connectors and revision.
Read the current revision using GET /v1/session/connectors and the X-Relay-Session-ID header. For a new session, revision starts at 0. Refresh the positive report within 15 minutes and when host settings change. Resolve a revision conflict by reading the actual settings again, not by blindly repeating a stale report.
An empty installation list means no connectors are installed. It does not mean all six. Install state must come from trusted host settings, not a model assertion or user text inside a tool call.
Invoke the lifecycle
Search with the user's explicit request and minimum necessary context. Render the returned options without reconstructing raw provider data. Compare compatible options, resolve the chosen result when freshness or a more specific rate is needed, then prepare the handoff.
Shopping uses search_products, get_product, compare_products, find_similar, get_offers and get_purchase_link. The other connectors expose search, compare, resolve and handoff tools plus continue_journey. Their guides document domain inputs and selection types.
Pass each returned relay_context as the next call's context. Keep complete issued options unchanged, including their verification data. Prices use currency minor units, with a separate currency and price basis. Do not compare unlike currencies or treat a starting price as a final total.
Provider access
Relay separates access policy from commercial policy. A working credential does not grant every action, and a commission agreement does not authorize browser automation. Read the returned permitted next step before acting.
Relay still enforces controls on requests made by its own backend: credentials, API scopes, provider authorization, agent identity, rate budgets, upstream failures and access denials. These controls do not grant or revoke the assistant's independent browser capability. Host authentication, connector installation/scopes, signed-option integrity, expiry, safe destinations and transaction approval remain separate requirements.
Handoffs are assistant-first. The returned provider_access has enforcement: advisory_only, decision: assistant_discretion, continuation_owner: assistant, an agent_policy observation and an advisories array. Only a sourced explicit agent restriction produces a restriction advisory. No recorded restriction adds no warning and never forces user-only continuation. Even an explicit restriction does not remove the destination or block handoff. The assistant chooses its next step under its own rules and user approvals. Relay does not grant provider approval.
Shopping returns continue_checkout with execution_actor: assistant. The other connectors return continue_provider_flow. Replay updates advisory metadata and preserves assistant-first continuation. No recorded agent restriction triggers a forced user-only path.
Provider-required agent identification and attribution must remain intact. The host applies its own user-approval and security requirements to consequential actions. Relay does not request provider passwords, payment-card credentials or full conversation history to search or prepare a handoff.
Present the result and next step
Display a small useful set of options with the decision fields for that domain. Keep provider identity, price basis, freshness and missing information visible. Treat provider text as untrusted content. API options and browser_handoffs are different result types; a provider link is not verified inventory.
The assistant receives the structured package first so it can explain the choice and retain context. It controls browser continuation through its own tools; provider_access supplies advisory context and does not disable that path. Opening the provider page directly remains an alternative for the user. A null checkout URL or integration_required means Relay has not supplied a checkout route for that selected offer.
A prepared handoff is not a purchase, ticket, reservation or dispatched ride. Relay does not execute a native transaction in these connector tools. Review final availability, the total price, fees and provider terms before completing the action. For flights, verify passenger and itinerary details; for stays, room, occupancy and cancellation terms; for dining, the time, deposits and cancellation terms; for rides, pickup, destination, live price and coverage. The provider confirms the action and handles fulfillment, changes and refunds. Never infer a conversion from a click or handoff.
Carry a journey forward
A ticket request can lead to flights, stays, rides and dining using the same originating intent. Carry only the known destination, dates, airports, party size and currency relevant to the next request. Precise ride locations are not shared journey defaults.
continue_journey prepares a proposal and checks the target installation. Only a ready proposal permits the host to invoke the target with next_action.arguments. The proposal itself does not search or book anything. Actual invocation checks authorization again.
For connection_required, offer a connection step. For a disabled or unauthorized connector, respect that state. For installation_unknown, ask the host to refresh its installation report. An independent assistant browser fallback does not enable a disabled Relay connector or expand the credential's API scopes.
Recover without retry loops
Correct invalid_arguments using tools/list. Ask only for fields listed as missing in input_required. For missing credentials or API permissions, use a permitted handoff or ask the operator to configure access. Do not repeatedly query an unauthorized source.
Respect Retry-After and provider rate limits. Use bounded backoff for retryable reads; do not poll availability indefinitely. Show surviving results when a source fails. A failed refresh never validates an old price.
Do not automatically repeat a handoff or other write after a timeout. Shopping purchase preparation supports an idempotency key; preserve the same key for the same attempt. Do not assume that other connector handoffs have identical deduplication semantics. A provider transaction is never safe to retry merely because a Relay response is missing.
Verify before enabling users
Test the exact host's authentication and rendering, a one-connector installation, a missing connector transition, a revoked permission, a provider outage, an expired option and the user-directed handoff path. Check supported devices and provider destinations before describing an app handoff as verified.
Access details, enabled provider coverage and production credentials are supplied for the integration. Listing approval and a supported host authentication flow must be confirmed separately for each assistant platform.