Appearance
Integration Options
Partners can access Vio's hotel search capabilities at whatever level of depth suits their product. All integration modes call the same Vio MCP tools — the difference is how much UI and interaction handling Vio provides.
Three principles underpin the platform:
- One MCP server. All modes call the same Vio MCP tools. The data layer is always Vio's.
- One component library.
@vio/ui-kitpowers every surface that renders hotel UI — partner apps, the MCP App, and Vio's own agent. - Partners own their agent. Vio never requires partners to adopt a specific agent framework.
Overview
| Integration | Partner builds | Vio provides | Best for |
|---|---|---|---|
| MCP Only | Everything | Data | Full-control builders |
| UI Kit Library | Shell + wiring | Data + UI components | Existing frontends |
| AG-UI + UI Kit | Agent + shell | Data + UI + interactions | AI-native products |
| Hosted MCP App | Nothing | Everything | Fastest time to market |
MCP Only
Data layer only · No Vio UI
The partner calls Vio's MCP tools directly from their agent. Vio provides hotel data in a structured format. The partner owns 100% of the UI and all interaction logic.
When to choose this mode. You have a mature design system and strong frontend team. You want Vio's data but have specific UI requirements that cannot be met by a component library.
What Vio provides: MCP server endpoint, API key, structured VioHotel[] data, TypeScript schema definitions.
What the partner owns: All UI components, interaction handling, agent logic, full request-response cycle.
Quick example: LangChain + MCP
typescript
import {MultiServerMCPClient} from '@langchain/mcp-adapters'
import {initChatModel} from 'langchain/chat_models/universal'
import {createReactAgent} from '@langchain/langgraph/prebuilt'
const mcpClient = new MultiServerMCPClient({
vio: {
transport: 'http',
url: 'https://mcp.vio.com/mcp?api_key=YOUR_API_KEY'
}
})
const tools = await mcpClient.getTools()
const llm = await initChatModel('gpt-4o', {streaming: true})
const agent = createReactAgent({llm, tools})See Examples for complete working implementations.
| Dimension | Detail |
|---|---|
| UI dependency | None — partner builds everything |
| Interaction handling | Partner implements all callbacks |
| Time to integrate | ~1 day |
| Upgrade path | Migrate to UI Kit Library or AG-UI without changing MCP calls |
UI Kit Library
Data + UI components · Agent renders independently of UI
The partner's agent calls Vio's MCP tools and the returned data is passed directly as props to Vio's pre-built React components. The agent drives data fetching but does not drive the UI — components render from props, and interactions are surfaced as callbacks.
When to choose this mode. You have an existing frontend and want to drop in Vio's hotel UI without restructuring your agent around AG-UI.
tsx
import { VioSearchResults } from '@vio/ui-kit-react';
const results = await callVioMCP('search_hotels', { destination, checkIn, checkOut, guests });
return (
<VioSearchResults
status="complete"
args={results}
theme={{ accent: '#6001D2' }}
onHotelSelect={(hotel) => navigate(`/hotel/${hotel.id}`)}
onPriceAlert={(hotel, price) => myBackend.createAlert(hotel.id, price)}
/>
);| Dimension | Detail |
|---|---|
| UI dependency | @vio/ui-kit-react |
| Interaction handling | Partner implements callback props |
| Time to integrate | ~2-4 hours |
| Customization | Theme, slot overrides, headless mode |
AG-UI + UI Kit
Data + UI + full interaction loop · AG-UI agent drives UI
The partner's agent uses the AG-UI protocol to communicate with their frontend. The agent calls Vio's MCP tools; AG-UI routes tool call events to @vio/ui-kit components which render automatically. User interactions flow back through the agent — the partner writes no interaction handling code.
When to choose this mode. You are building an AI-native product — a chat interface, an AI search mode, a travel planning agent — and your agent is AG-UI compatible or you are willing to adopt it. This is the recommended mode for AI browser and search partners.
Why the interaction loop matters. As Vio's component library grows — more filters, a map view, a comparison tray, a checkout button — every new interaction is handled automatically by the AG-UI event loop. The partner's integration code does not grow.
AG-UI is an open protocol supported by LangGraph, CrewAI, Mastra, PydanticAI, AWS Strands, CopilotKit, and others. For CopilotKit partners:
tsx
import { useVioActions } from '@vio/ui-kit-agui/copilotkit';
export function TravelPage() {
useVioActions({ accent: '#6001D2' });
return <CopilotChat />;
}| Dimension | Detail |
|---|---|
| UI dependency | @vio/ui-kit-agui + @vio/ui-kit-core |
| Interaction handling | Automatic — AG-UI event loop |
| Time to integrate | ~2 hours (CopilotKit) / ~half day (raw AG-UI) |
| Future capabilities | Automatic — new components ship via npm update |
Hosted MCP App
Zero integration · Fully hosted by Vio
Vio provides a fully hosted, ready-to-use hotel search application. Partners embed it via an iframe or webview. No npm dependency. No code. The partner provides a placement and Vio provides everything else.
When to choose this mode. You want the fastest possible time to market with no engineering investment. Good as a starting point before graduating to UI Kit Library or AG-UI.
See the Vio ChatGPT App for a live example.
| Dimension | Detail |
|---|---|
| UI dependency | None — fully hosted |
| Interaction handling | Fully handled by Vio |
| Time to integrate | ~30 minutes |
| Partner control | None over UI or interactions |
Choosing the right mode
| Question | Recommendation |
|---|---|
| Is your agent AG-UI compatible? | Yes — AG-UI + UI Kit. Not yet — UI Kit Library or assess migration path. |
| Do you want full control over hotel UI? | Yes — MCP Only or UI Kit Library with headless customization. |
| Do you want the fastest time to market? | Yes — Hosted MCP App, then migrate to UI Kit Library or AG-UI. |
| Do you want Vio UI improvements automatically? | Yes — AG-UI + UI Kit or Hosted MCP App. UI Kit Library requires npm updates. |
| Do you want to own interaction handling? | Yes — UI Kit Library. No — AG-UI + UI Kit. |
The shared UI layer
Every mode that renders hotel UI draws from a single component library. UI improvements ship everywhere at once.
| Package | Purpose |
|---|---|
@vio/ui-kit-core | Framework-agnostic hotel UI components. The single source of truth for how hotel information looks. |
@vio/ui-kit-agui | AG-UI wiring layer. Maps tool call events to the correct @vio/ui-kit-core components automatically. |
@vio/ui-kit-react | Thin React wrapper around @vio/ui-kit-core for partners importing components directly. |
Migration paths
Integration modes are additive. A partner can start at a lower mode and migrate upward without changing their MCP integration.
| Migration | What changes |
|---|---|
| MCP Only → UI Kit Library | Add @vio/ui-kit-react. Replace custom components with Vio components. MCP calls unchanged. |
| UI Kit Library → AG-UI | Add @vio/ui-kit-agui. Adopt AG-UI in the agent. Remove callback implementations. MCP calls unchanged. |
| Hosted MCP App → UI Kit Library | Remove iframe. Add @vio/ui-kit-react. Add MCP integration. Gain UI control. |
| Hosted MCP App → AG-UI | Remove iframe. Add AG-UI to agent. Add @vio/ui-kit-agui. Full AI-native integration. |
Attribution and tracking
Each partner receives a unique API key. All searches and bookings made through your integration are automatically attributed to your product. This enables:
- Click and conversion analytics
- Revenue attribution and reporting
- Usage monitoring
Rate limits
Rate limits are configured per API key. Default limits are generous for production use. Contact your Vio representative if you need higher throughput.