# MCP App Fallback Architecture
## Graceful Degradation for Hosts Without Full Interactive Support
**Date:** 2026-02-03
**Status:** Proposed
**Applies to:** GoHighLevel MCP UI Kit React App
---
## Executive Summary
The ext-apps SDK provides explicit **host capability negotiation** via `McpUiHostCapabilities`. After the `ui/initialize` handshake, the View knows exactly which features the host supports. We use this to implement a **three-tier progressive enhancement** model: Static → Context-Synced → Fully Interactive.
---
## 1. Feature Detection (The Foundation)
### How It Works
When the View connects, the host returns `McpUiHostCapabilities` in the `ui/initialize` response. The `App` class exposes this via `app.getHostCapabilities()`.
**The key capability flags:**
```typescript
interface McpUiHostCapabilities {
serverTools?: { listChanged?: boolean }; // Can proxy tools/call to MCP server
serverResources?: { listChanged?: boolean }; // Can proxy resources/read
updateModelContext?: {}; // Accepts ui/update-model-context
message?: {}; // Accepts ui/message (send chat messages)
openLinks?: {}; // Can open external URLs
logging?: {}; // Accepts log messages
sandbox?: { permissions?: {...}; csp?: {...} };
}
```
**The critical check: `serverTools` tells you if `callServerTool` will work.**
### Implementation: `useHostCapabilities` Hook
```typescript
// hooks/useHostCapabilities.ts
import { useMemo } from "react";
import { useMCPApp } from "../context/MCPAppContext.js";
import type { McpUiHostCapabilities } from "@modelcontextprotocol/ext-apps";
export type InteractionTier = "static" | "context-synced" | "full";
export interface HostCapabilityInfo {
/** Raw capabilities from the host */
raw: McpUiHostCapabilities | undefined;
/** Whether callServerTool() will work */
canCallTools: boolean;
/** Whether updateModelContext() will work */
canUpdateContext: boolean;
/** Whether sendMessage() will work */
canSendMessages: boolean;
/** The interaction tier this host supports */
tier: InteractionTier;
}
export function useHostCapabilities(): HostCapabilityInfo {
const { app } = useMCPApp();
return useMemo(() => {
const raw = app?.getHostCapabilities?.() as McpUiHostCapabilities | undefined;
const canCallTools = !!raw?.serverTools;
const canUpdateContext = !!raw?.updateModelContext;
const canSendMessages = !!raw?.message;
// Determine tier
let tier: InteractionTier = "static";
if (canCallTools) {
tier = "full";
} else if (canUpdateContext) {
tier = "context-synced";
}
return { raw, canCallTools, canUpdateContext, canSendMessages, tier };
}, [app]);
}
```
### Add to MCPAppContext
```typescript
// In MCPAppContext.tsx — extend the context value:
export interface MCPAppContextValue {
// ... existing fields ...
/** Host capability info, available after connection */
capabilities: HostCapabilityInfo;
/** Safe tool call: uses callServerTool if available,
falls back to updateModelContext, or no-ops */
safeCallTool: (
toolName: string,
args: Record<string, any>,
options?: { localOnly?: boolean }
) => Promise<CallToolResult | null>;
}
```
---
## 2. The Three-Tier Model
### Tier 1: Static (No host capabilities)
- Pure data visualization — charts, tables, badges, timelines
- All data comes from the initial `ontoolresult` payload
- No server communication, no context updates
- **Components work as-is:** BarChart, PieChart, StatusBadge, DataTable, Timeline, etc.
### Tier 2: Context-Synced (`updateModelContext` available, no `serverTools`)
- Local interactivity works (drag, edit, toggle, form fills)
- User actions update LOCAL state immediately
- State changes are synced to the LLM via `updateModelContext`
- The LLM can then decide to call tools itself on the next turn
- **Key pattern:** User drags a Kanban card → local state updates → `updateModelContext` tells the LLM what happened → LLM calls `move_opportunity` on its own
### Tier 3: Full Interactive (`serverTools` available)
- Everything works as currently designed
- Components call `callServerTool` directly for real-time server mutations
- Optimistic UI with server confirmation
```
┌─────────────────────────────────────────────────┐
│ TIER 3: FULL │
│ callServerTool ✓ updateModelContext ✓ │
│ Direct server mutations, optimistic UI │
│ ┌─────────────────────────────────────────────┐ │
│ │ TIER 2: CONTEXT-SYNCED │ │
│ │ callServerTool ✗ updateModelContext ✓ │ │
│ │ Local state + LLM-informed sync │ │
│ │ ┌─────────────────────────────────────────┐│ │
│ │ │ TIER 1: STATIC ││ │
│ │ │ Read-only data visualization ││ │
│ │ │ Charts, tables, badges, timelines ││ │
│ │ └─────────────────────────────────────────┘│ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
```
---
## 3. Component Classification
### Always Static (work everywhere)
These components are pure data display — they render from the UITree data and never call tools:
| Component | Category |
|-----------|----------|
| BarChart, LineChart, PieChart, SparklineChart, FunnelChart | charts |
| StatusBadge, ProgressBar, CurrencyDisplay, StarRating | data |
| DataTable, KeyValueList, TagList, AvatarGroup | data |
| Timeline, MetricCard, DetailHeader, InfoBlock | data |
| PageHeader, Section, Card, StatsGrid, SplitLayout | layout |
| ChatThread, TranscriptView, EmailPreview, ContentPreview | comms |
| CalendarView, TreeView, FlowDiagram, DuplicateCompare | viz |
### Context-Syncable (Tier 2+)
These work with local state and sync via `updateModelContext`:
| Component | Local Behavior | Context Sync |
|-----------|---------------|--------------|
| KanbanBoard | Drag cards between columns locally | Report new board state to LLM |
| EditableField | Edit text inline locally | Report edited values to LLM |
| FormGroup | Fill form fields locally | Report form state to LLM |
| SelectDropdown | Select options locally | Report selection to LLM |
| AmountInput | Adjust amounts locally | Report new amounts to LLM |
| ChecklistView | Toggle checkboxes locally | Report checklist state to LLM |
| FilterChips | Toggle filters locally | Report active filters to LLM |
| TabGroup | Switch tabs locally | Report active tab to LLM |
| SearchBar | Type search queries locally | Report search to LLM |
### Full Interactive Only (Tier 3)
These **require** server tool calls and degrade gracefully at lower tiers:
| Component | Tier 3 | Tier 2 Fallback | Tier 1 Fallback |
|-----------|--------|-----------------|-----------------|
| ActionButton | Calls tool | Shows "Ask assistant" hint | Disabled/hidden |
| AppointmentBooker | Books via tool | Shows form, reports to LLM | Shows read-only schedule |
| InvoiceBuilder | Creates via tool | Builds locally, reports to LLM | Shows existing invoice data |
| OpportunityEditor | Saves via tool | Edits locally, reports to LLM | Shows read-only data |
| ContactPicker | Searches via tool | Shows static options list | Shows read-only display |
---
## 4. Concrete Implementation
### 4a. `safeCallTool` — The Universal Action Handler
```typescript
// In MCPAppProvider
const safeCallTool = useCallback(
async (
toolName: string,
args: Record<string, any>,
options?: { localOnly?: boolean }
): Promise<CallToolResult | null> => {
// Tier 3: Full tool call
if (capabilities.canCallTools && !options?.localOnly) {
return callTool(toolName, args);
}
// Tier 2: Inform LLM via updateModelContext
if (capabilities.canUpdateContext && app) {
const markdown = [
`---`,
`action: ${toolName}`,
`timestamp: ${new Date().toISOString()}`,
...Object.entries(args).map(([k, v]) => `${k}: ${JSON.stringify(v)}`),
`---`,
`User performed action "${toolName}" in the UI.`,
`Please execute the corresponding server-side operation.`,
].join("\n");
await app.updateModelContext({
content: [{ type: "text", text: markdown }],
});
// Return a synthetic "pending" result
return {
content: [
{
type: "text",
text: `Action "${toolName}" reported to assistant. It will be processed on the next turn.`,
},
],
} as CallToolResult;
}
// Tier 1: No-op, return null
console.warn(`[MCPApp] Cannot execute ${toolName}: no host support`);
return null;
},
[capabilities, callTool, app]
);
```
### 4b. `<InteractiveGate>` — Tier-Aware Wrapper
```tsx
// components/shared/InteractiveGate.tsx
import React from "react";
import { useHostCapabilities, type InteractionTier } from "../../hooks/useHostCapabilities.js";
interface InteractiveGateProps {
/** Minimum tier required to show children */
requires: InteractionTier;
/** What to render if the tier isn't met */
fallback?: React.ReactNode;
/** If true, hide entirely instead of showing fallback */
hideOnUnsupported?: boolean;
children: React.ReactNode;
}
const tierLevel: Record<InteractionTier, number> = {
static: 0,
"context-synced": 1,
full: 2,
};
export const InteractiveGate: React.FC<InteractiveGateProps> = ({
requires,
fallback,
hideOnUnsupported = false,
children,
}) => {
const { tier } = useHostCapabilities();
if (tierLevel[tier] >= tierLevel[requires]) {
return <>{children}</>;
}
if (hideOnUnsupported) return null;
if (fallback) return <>{fallback}</>;
// Default fallback: subtle message
return (
<div className="interactive-unavailable" role="note">
<span className="interactive-unavailable-icon">ℹ️</span>
<span>This feature requires a supported host. Ask the assistant to perform this action.</span>
</div>
);
};
```
### 4c. Refactored `ActionButton` with Fallback
```tsx
// components/shared/ActionButton.tsx (revised)
export const ActionButton: React.FC<ActionButtonProps> = ({
label,
variant = "secondary",
size = "md",
disabled,
toolName,
toolArgs,
}) => {
const { safeCallTool } = useMCPApp();
const { tier, canCallTools, canSendMessages } = useHostCapabilities();
const [loading, setLoading] = useState(false);
const [pendingMessage, setPendingMessage] = useState<string | null>(null);
const handleClick = useCallback(async () => {
if (!toolName || loading || disabled) return;
setLoading(true);
setPendingMessage(null);
try {
const result = await safeCallTool(toolName, toolArgs || {});
// Tier 2: show "reported to assistant" feedback
if (!canCallTools && result) {
setPendingMessage("Reported to assistant");
setTimeout(() => setPendingMessage(null), 3000);
}
} catch {
// handled by context
} finally {
setLoading(false);
}
}, [toolName, toolArgs, loading, disabled, safeCallTool, canCallTools]);
// Tier 1 with no context sync: show disabled with hint
if (tier === "static" && toolName) {
return (
<button className={`btn ${vCls} ${sCls} btn-unsupported`} disabled title="Ask the assistant to perform this action">
{label}
</button>
);
}
return (
<button className={`btn ${vCls} ${sCls}`} disabled={disabled || loading} onClick={handleClick}>
{loading && <span className="loading-spinner" style={{ width: 14, height: 14, marginRight: 6, borderWidth: 2, display: "inline-block" }} />}
{label}
{pendingMessage && <span className="btn-pending-badge">{pendingMessage}</span>}
</button>
);
};
```
### 4d. Refactored `KanbanBoard` — Local-First + Context Sync
The KanbanBoard already uses optimistic local state. The only change: fall back to `updateModelContext` when `moveTool` can't be called directly.
```tsx
// In KanbanBoard onDrop handler (revised):
const onDrop = useCallback(async (e: React.DragEvent, toStageId: string) => {
e.preventDefault();
setDropTargetStage(null);
const drag = dragRef.current;
if (!drag) return;
const { cardId, fromStageId } = drag;
dragRef.current = null;
setDraggingCardId(null);
if (fromStageId === toStageId) return;
// 1. Optimistic local update (same as before)
let movedCard: KanbanCard | undefined;
const prevColumns = columns;
setColumns(prev => { /* ... same optimistic logic ... */ });
// 2. Use safeCallTool — works at Tier 2 AND Tier 3
if (moveTool) {
try {
const result = await safeCallTool(moveTool, {
opportunityId: cardId,
pipelineStageId: toStageId,
});
// Tier 2: result is a "reported" message — no revert needed
// Local state IS the source of truth until LLM processes it
if (!capabilities.canCallTools && result) {
// Also report the full board state so LLM has context
await reportBoardState();
}
} catch (err) {
// Only revert if we attempted a real tool call (Tier 3)
if (capabilities.canCallTools) {
console.error("KanbanBoard: move failed, reverting", err);
setColumns(prevColumns);
}
}
}
}, [columns, moveTool, safeCallTool, capabilities]);
// Report full board state to LLM for context
const reportBoardState = useCallback(async () => {
if (!app || !capabilities.canUpdateContext) return;
const summary = columns.map(col =>
`**${col.title}** (${col.cards?.length ?? 0}):\n` +
(col.cards || []).map(c => ` - ${c.title} (${c.value || 'no value'})`).join('\n')
).join('\n\n');
await app.updateModelContext({
content: [{
type: "text",
text: `---\ncomponent: kanban-board\nupdated: ${new Date().toISOString()}\n---\nCurrent pipeline state:\n\n${summary}`,
}],
});
}, [app, capabilities, columns]);
```
### 4e. Refactored `EditableField` — Works at All Tiers
```tsx
// In EditableField (revised handleSave):
const handleSave = async () => {
setIsEditing(false);
if (editValue === value) return;
if (saveTool) {
const result = await safeCallTool(saveTool, {
...saveArgs,
value: editValue,
});
// Tier 2: field stays locally updated; LLM is informed
// Tier 3: server confirms; UI may refresh via ontoolresult
// Tier 1: nothing happens — but user sees their edit locally
if (!result && tier === "static") {
// Show hint that the change is display-only
setLocalOnlyHint(true);
setTimeout(() => setLocalOnlyHint(false), 3000);
}
}
};
```
---
## 5. Alternative Interaction: `updateModelContext` as Primary Channel
For hosts that support `updateModelContext` but not `serverTools`, we can use a **declarative intent** pattern instead of imperative tool calls:
```typescript
// hooks/useReportInteraction.ts
export function useReportInteraction() {
const { app } = useMCPApp();
const { canUpdateContext } = useHostCapabilities();
return useCallback(
async (interaction: {
component: string;
action: string;
data: Record<string, any>;
suggestion?: string; // What we suggest the LLM should do
}) => {
if (!canUpdateContext || !app) return;
const text = [
`---`,
`component: ${interaction.component}`,
`action: ${interaction.action}`,
`timestamp: ${new Date().toISOString()}`,
...Object.entries(interaction.data).map(([k, v]) => `${k}: ${JSON.stringify(v)}`),
`---`,
interaction.suggestion || `User performed "${interaction.action}" in ${interaction.component}.`,
].join("\n");
await app.updateModelContext({
content: [{ type: "text", text }],
});
},
[app, canUpdateContext]
);
}
```
**Usage in any component:**
```tsx
const reportInteraction = useReportInteraction();
// In a form submit handler:
await reportInteraction({
component: "AppointmentBooker",
action: "book_appointment",
data: { contactId, calendarId, startTime, endTime },
suggestion: "User wants to book this appointment. Please call create_appointment with these details.",
});
```
---
## 6. Server-Side: Dual-Mode Tool Registration
The MCP server should register tools that work both ways:
```typescript
// Server-side: Register tool as visible to both model and app
registerAppTool(server, "move_opportunity", {
description: "Move an opportunity to a different pipeline stage",
inputSchema: {
opportunityId: z.string(),
pipelineStageId: z.string(),
},
_meta: {
ui: {
resourceUri: "ui://ghl/pipeline-view",
visibility: ["model", "app"], // ← Both can call it
},
},
}, handler);
```
With `visibility: ["model", "app"]`:
- **Tier 3 hosts:** App calls it directly via `callServerTool`
- **Tier 2 hosts:** App reports intent via `updateModelContext`, LLM sees the tool in its tool list and calls it on the next turn
- **Tier 1 hosts:** Tool still works as text-only through normal MCP
---
## 7. `window.__MCP_APP_DATA__` Pre-Injection (Tier 0)
The existing `getPreInjectedTree()` in App.tsx already supports a non-MCP path. For environments where the iframe loads but the ext-apps SDK never connects:
```typescript
// App.tsx already handles this:
useEffect(() => {
const preInjected = getPreInjectedTree();
if (preInjected && !uiTree) {
setUITree(preInjected);
}
}, []);
```
This serves as **Tier 0**: pure server-side rendering. The server injects the UITree directly into the HTML. No SDK connection needed. All components render in static mode.
---
## 8. CSS for Degraded States
```css
/* styles/fallback.css */
/* Unsupported interactive elements */
.btn-unsupported {
opacity: 0.6;
cursor: not-allowed;
position: relative;
}
.btn-unsupported::after {
content: "↗";
font-size: 0.7em;
margin-left: 4px;
opacity: 0.5;
}
/* "Reported to assistant" badge */
.btn-pending-badge {
margin-left: 8px;
font-size: 0.75em;
color: var(--color-text-info, #3b82f6);
animation: fadeIn 0.2s ease-in;
}
/* Unavailable feature hint */
.interactive-unavailable {
display: flex;
align-items: center;
gap: 8px;
padding: 8px 12px;
border-radius: var(--border-radius-md, 6px);
background: var(--color-background-info, #eff6ff);
color: var(--color-text-secondary, #6b7280);
font-size: 0.85em;
}
/* Local-only edit hint */
.ef-local-hint {
font-size: 0.75em;
color: var(--color-text-warning, #f59e0b);
margin-top: 2px;
}
/* Editable fields in static mode: remove edit affordance */
[data-tier="static"] .ef-edit-icon {
display: none;
}
[data-tier="static"] .ef-display {
cursor: default;
}
```
---
## 9. Decision Matrix
| Scenario | Detection | Behavior |
|----------|-----------|----------|
| Claude Desktop (full support) | `serverTools` ✓ | Tier 3: all features work |
| Host with context-only support | `updateModelContext` ✓, `serverTools` ✗ | Tier 2: local + LLM sync |
| Minimal host / basic iframe | No capabilities | Tier 1: static display |
| Pre-injected `__MCP_APP_DATA__` | No SDK connection | Tier 0: SSR static |
| `callServerTool` fails at runtime | Error caught | Downgrade to Tier 2 dynamically |
---
## 10. Summary: What to Implement
### Phase 1 (Essential)
1. **`useHostCapabilities` hook** — reads `app.getHostCapabilities()`, computes tier
2. **`safeCallTool` in MCPAppContext** — wraps callTool with fallback to updateModelContext
3. **Update `ActionButton`** — use safeCallTool, show disabled state at Tier 1
4. **Update `KanbanBoard`** — already local-first, just wire up safeCallTool + reportBoardState
5. **`fallback.css`** — styles for degraded states
### Phase 2 (Full Coverage)
6. **`useReportInteraction` hook** — standard way to inform LLM of UI actions
7. **`<InteractiveGate>` component** — declarative tier gating in templates
8. **Update all interactive components** — EditableField, FormGroup, AppointmentBooker, etc.
9. **Runtime downgrade** — if a Tier 3 call fails, auto-downgrade to Tier 2
### Phase 3 (Polish)
10. **Toast notifications** for tier-specific feedback ("Action sent to assistant")
11. **`data-tier` attribute** on root for CSS-only degradation
12. **Testing matrix** — automated tests per tier per component
---
## Key Insight
The ext-apps spec was **designed** for this: *"UI is a progressive enhancement, not a requirement."* Our architecture mirrors this philosophy — every component starts as a static data display and progressively gains interactivity based on what the host reports it can do. The KanbanBoard's existing optimistic-update pattern is already the correct Tier 2 pattern; we just need to formalize it and apply it consistently.
