GUI3: Add MCP support (proposal / discussion)

[kpoineal]

Summary

"MCP support in GUI3" means two things:

1. Surface lemonade's existing MCP server — let the GUI3 user see, test, and manage the POST /mcp endpoint that lemond already exposes (tool listing, connection URL copy, health).
2. MCP client/host in GUI3 — let GUI3 connect to external MCP servers (e.g. filesystem, GitHub, custom tools) and surface their tools in the chat panel alongside lemonade's native tools.

User-facing value: Power users connecting Claude Desktop, Cursor, or other MCP clients to lemonade today have no GUI visibility into what's happening. And users who want to consume external MCP tools from the GUI3 chat have no way to do so — they're limited to the hardcoded lemonade tool set in tools/lemonadeTools.ts.

---

Current State — We Are NOT Starting From Zero

Lemonade already ships a full MCP gateway:

What	Where	Details
MCP server impl	src/cpp/server/mcp_server.cpp	JSON-RPC 2.0, Streamable HTTP transport, protocol version 2025-06-18
Route registration	src/cpp/server/server.cpp:694-698	POST /mcp (intentional exception to quad-prefix invariant per AGENTS.md #1)
GET rejection	mcp_server.cpp:250-259	Returns 405 with Allow: POST header
Auth	server.cpp:361-367	LEMONADE_API_KEY enforcement covers /mcp

Exposed Tools (5)

Tool	Purpose
lemonade_list_models	Discover loaded/available/suggested models
lemonade_chat	Chat completion against a local LLM
lemonade_transcribe_audio	Whisper-class transcription
lemonade_generate_image	Stable Diffusion image generation (sandbox-confined writes)
lemonade_omni	Multimodal turn via Omni collections (text + image + speech)

GUI3 Existing Tool Infrastructure

GUI3 already has a tools/ directory:

• prototype/ui-redesign/src/tools/lemonadeTools.ts — OpenAI function-calling tool definitions for model management (list, load, unload, pull, etc.)
• prototype/ui-redesign/src/tools/omniTools.ts — Omni collection tool routing

The chat panel (ChatView.tsx) already executes tool calls via useChatStreaming hook + ChatToolRuntime. This is the natural integration point.

---

Proposed Implementation

Direction: Both — but phased

Phase	Direction	Server changes needed?
A (POC)	Surface lemonade's own MCP server status in GUI3	❌ No — read-only against existing /mcp
B (POC)	GUI3 as MCP client connecting to external servers	❌ No — frontend HTTP calls to external MCP endpoints
C (post-POC)	Server-side MCP client registry in lemond config	✅ Yes — deferred, requires lemond changes

Phase A — MCP Server Dashboard (frontend-only)

Where it lives: New panel in ConnectView.tsx (which already handles server connection, cloud providers, and marketplace apps) or a dedicated "Integrations" tab.

What it shows:

• MCP endpoint URL ({baseUrl}/mcp) with copy button
• Protocol version (2025-06-18)
• List of 5 exposed tools with descriptions (fetched via tools/list JSON-RPC call to /mcp)
• Connection snippet for Claude Desktop / Cursor / other clients
• Health indicator (can we reach /mcp?)

Implementation:

// New: prototype/ui-redesign/src/features/mcp/McpServerStatus.tsx
// Calls POST /mcp with {"jsonrpc":"2.0","method":"tools/list","id":1}
// Renders tool cards with name + description + inputSchema summary

Phase B — MCP Client Host (frontend-only, Streamable HTTP)

Where it lives: New prototype/ui-redesign/src/features/mcp/McpClientManager.tsx + integration into ChatView.tsx's tool runtime.

How it works:

1. User adds external MCP server URLs in a settings panel (stored in localStorage per invariant Request to you for benchmark report #11)
2. On connect, GUI3 sends initialize → tools/list to each external server via Streamable HTTP (POST)
3. Discovered tools are merged into the tool palette visible in chat
4. When the LLM returns a tool call matching an external MCP tool, GUI3 dispatches tools/call to the appropriate external server
5. Results flow back into the chat stream

Key architectural points:

• Transport: Streamable HTTP only (POST with JSON-RPC body). No stdio — GUI3 runs in a browser/webview, not a shell.
• Invariant Request to you for benchmark report #11 (many-clients-one-server): External MCP server config is per-client (localStorage), NOT stored in lemond. Each GUI3 instance can have its own set of connected MCP servers.
• Invariant Release v7.0.1 #13 (on-demand desktop): MCP client connections are lazy — only established when the user opens GUI3 and navigates to a chat that uses them.
• Auth passthrough: If an external MCP server requires auth, the user provides it in the GUI3 settings panel. LEMONADE_API_KEY applies only to lemonade's own /mcp endpoint.

Integration with existing tool infrastructure:

ChatView.tsx
  └── useChatStreaming hook
       └── ChatToolRuntime (existing)
            ├── lemonadeTools.ts (existing — list_models, load, unload, etc.)
            ├── omniTools.ts (existing — Omni collection routing)
            └── mcpClientTools.ts (NEW — dispatches to external MCP servers)

Phase C — Server-Side Registry (post-POC, requires lemond changes)

Flag for later: if we want lemond itself to act as an MCP client (so CLI users and all GUI clients share the same external tool set), that requires:

• New config section in config.json for MCP server registry
• lemond connects to external MCP servers on startup
• External tools become available via the existing /mcp gateway (tool passthrough)

This is explicitly out of scope for the UI POC but noted here for completeness.

---

Integration with Existing MCP Tools — Avoiding Duplication

The 5 existing MCP tools (lemonade_*) and the GUI3 lemonadeTools.ts tools serve different consumers:

Consumer	Tool set	Transport
External MCP clients (Claude, Cursor)	lemonade_* via POST /mcp	JSON-RPC 2.0 / Streamable HTTP
GUI3 chat panel (LLM function calling)	lemonadeTools.ts via direct HTTP	OpenAI function-calling format

No duplication risk — they're different protocols for different consumers. The MCP client feature (Phase B) adds a third category: external tools from other MCP servers, surfaced in GUI3's chat.

If in Phase C we ever want GUI3 to use lemonade's own tools through the MCP protocol (instead of direct HTTP), that would be a unification opportunity — but it adds a JSON-RPC hop with no user benefit today.

---

Open Questions for @fl0rianr

1. Client vs. server scope for the POC: Should Phase A (MCP server dashboard) and Phase B (MCP client host) both land in the POC, or should we defer Phase B to post-POC? Phase A is low-risk (read-only); Phase B is more complex but arguably the higher user value.

2. External MCP server config location: Per invariant Request to you for benchmark report #11, this should be client-local (localStorage). But should we pre-populate a "suggested servers" list (like the marketplace in ConnectView.tsx)? Or keep it fully manual for now?

3. Auth model for external MCP servers: Plain bearer token per server? Or do we need to support OAuth/PKCE flows that some MCP servers require? For the POC, I'd propose token-only and flag OAuth as Phase C.

4. Tool conflict resolution: If an external MCP server exposes a tool with the same name as a lemonade native tool (e.g. list_models), what's the precedence? Namespace prefixing (servername/toolname)? Or reject duplicates?

5. Where in the GUI3 nav: Dedicated "Integrations" / "MCP" view? Or fold into the existing ConnectView which already has server settings + cloud providers + marketplace?

6. SSE streaming: The current /mcp endpoint is POST-only (no SSE channel — mcp_server.cpp:251 comment says "No SSE channel in this MVP"). For Phase B external servers, should GUI3 support SSE-based MCP transport, or is Streamable HTTP (POST) sufficient for the POC?

---

@fl0rianr — Would love your thoughts on the approach above, especially the phasing and whether the MCP client host (Phase B) belongs in the POC or should wait. The existing /mcp gateway gives us a solid foundation; the question is how much of the client-side story we tackle now vs. later.

[fl0rianr]

Thanks for writing this up — the split between “surfacing lemonade’s own MCP server” and “GUI3 as an MCP client/host” makes sense to me.

My take on the POC scope:

1. Phase A should definitely be in the POC.
   Surfacing the existing /mcp endpoint in GUI3 is low-risk, frontend-only, and gives immediate user value: endpoint visibility, copyable connection info, health/status, and the list of exposed tools.

2. Phase B is valuable, but I would keep it either behind an experimental flag or as a follow-up after Phase A lands.
   Having GUI3 consume external MCP servers is the more interesting feature, but it also introduces more product/security surface: auth handling, tool permissions, naming conflicts, CORS/browser-webview constraints, error states, and potentially untrusted external tools. I would avoid letting that complexity block the server-dashboard work.

For the open questions:

• Config location: client-local is the right default for the POC. localStorage fits the many-clients-one-server invariant. I would start with fully manual server URLs and maybe add suggested templates later.
• Auth: token/header-based auth only for the POC. OAuth/PKCE should be explicitly out of scope until we know we need it.
• Tool conflict resolution: I’d namespace external MCP tools internally, for example by server id/name plus tool name, while keeping the display label user-friendly. I would avoid letting third-party tools collide with native lemonade tools.
• GUI placement: ConnectView or a new “Integrations” area both make sense. My preference would be to start in ConnectView if that already owns connection/provider setup, then split into a dedicated Integrations/MCP view once the feature grows.
• Transport: Streamable HTTP POST-only is sufficient for the POC. I would not add SSE support yet unless we have a concrete external server requirement.
• Native lemonade tools: I would not route GUI3’s existing native tools through MCP in this POC. The current direct HTTP/OpenAI-function-calling path is fine; MCP can remain the protocol boundary for external clients and external tools.

So my suggested path would be:

• Land Phase A first as a clean, read-only MCP status/dashboard panel.
• Design Phase B in parallel, but keep the first implementation minimal and experimental: manual server URL, token/header auth, initialize + tools/lis` + tools/call, namespaced tools, Streamable HTTP only.
• Defer server-side registry, OAuth, SSE, and deeper tool-permission UX to post-POC.

This gives us visible MCP support quickly without overcommitting the first GUI3 implementation.

[kpoineal]

Phase B Design: GUI3 as MCP Client Host (Experimental)

Author: @kpoineal (via Lovell, lead engineer)
Date: 2026-06-25
Status: Design proposal — experimental, flag-gated, no lemond changes
Depends on: Phase A (#2404) merged first; Phase B does NOT block Phase A

---

0. Scope & constraints (per @fl0rianr's answers)

• Experimental / behind a feature flag — localStorage key lemonade_mcp_client_enabled.
• Transport: Streamable HTTP POST-only (JSON-RPC 2.0, protocol 2025-06-18). No SSE.
• Config: client-local localStorage. Manual server URLs; templates deferred.
• Auth: static token/header only. OAuth/PKCE out of scope.
• Tool conflicts: namespace by server id + tool name; never collide with native tools.
• GUI placement: starts in ConnectView; splits into dedicated Integrations panel when it grows.
• Native GUI3 tools stay native — they are NOT routed through MCP.
• Deferred: server-side registry, OAuth, SSE, deep tool-permission UX.

---

1. Data model / state (client-local, per invariant #11)

All state lives in localStorage under scoped keys (respecting the existing scopedStorageKey() pattern from accountStore.ts). No lemond endpoints.

// localStorage key: lemonade_mcp_servers
interface McpServerEntry {
  id: string;              // user-chosen slug, e.g. "my-rag-server"
  label: string;           // display name
  baseUrl: string;         // e.g. "https://my-server.example.com/mcp"
  authHeader?: string;     // e.g. "Bearer sk-..." — stored as-is
  enabled: boolean;        // toggle without deleting
  protocolVersion?: string;// negotiated version after initialize
  lastConnectedAt?: string;// ISO timestamp
  lastError?: string;      // human-readable error from last attempt
}

// localStorage key: lemonade_mcp_client_enabled
// Value: "true" | absent → feature flag gate

Why localStorage, not IndexedDB: consistency with existing preset/account storage patterns; MCP server list is small (< 50 entries); no binary blobs.

Many-clients-one-server invariant (#11): each client (desktop webview, web-app, different machine) maintains its own MCP server list. Two clients can register different external MCP servers — lemond is unaware. This is correct: the MCP client runs in the browser/webview, not in the C++ server.

---

2. Connection lifecycle (POST-only Streamable HTTP)

All communication uses fetch() from the browser/webview. No WebSocket, no SSE.

2.1 Handshake: initialize

POST {baseUrl}
Content-Type: application/json
Authorization: {authHeader}           // if configured
Mcp-Session-Id: (omitted on first call)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": {} },
    "clientInfo": {
      "name": "lemonade-gui3",
      "version": "<from package.json>"
    }
  }
}

Response processing:

1. Extract Mcp-Session-Id header → store in memory (not localStorage — session-scoped).
2. Validate result.protocolVersion — must match 2025-06-18. If not, set lastError, mark server as disconnected.
3. Store negotiated capabilities and serverInfo in React state.
4. Send notifications/initialized (no id field — it's a notification).

2.2 tools/list

POST {baseUrl}
Mcp-Session-Id: {sessionId}
Authorization: {authHeader}

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

Response result.tools[] are cached in React state, keyed by server id. Each tool is namespaced (see §3).

2.3 Error / timeout / disconnect states

State	Trigger	UI	Recovery
disconnected	Initial / explicit disconnect	Grey dot	Manual "Connect" button
connecting	initialize in flight	Spinner	—
connected	Successful initialize + tools/list	Green dot	—
error	Non-2xx response, network error, version mismatch	Red dot + lastError	"Retry" button
timeout	fetch exceeds 15 s	Red dot + timeout message	"Retry"

No automatic reconnect in POC. User clicks "Retry" or "Connect".

---

3. Tool integration into chat

3.1 Namespacing

External tools are namespaced as mcp_{serverId}_{toolName} in the OpenAI function-calling schema sent to the LLM. Example: server id my-rag, tool name search_docs → function name mcp_my-rag_search_docs.

Display label shown to user: "{serverLabel} → {tool.name}" (e.g., "My RAG → search_docs").

Collision rule: if mcp_{serverId}_{toolName} collides with any name in LEMONADE_TOOLS (from lemonadeTools.ts), the external tool is rejected at registration time with a clear error message. Native tools always win.

3.2 Integration with ChatToolRuntime

The existing ChatToolRuntime interface (useChatStreaming.ts:28-32) already supports pluggable tool sets:

export interface ChatToolRuntime {
  tools: Record<string, unknown>[];           // OpenAI function schemas
  execute: (call: ToolCall) => Promise<ToolExecutionPayload>;
  systemPrompt?: string;
}

Phase B creates a merged runtime when the feature flag is on:

function buildMergedToolRuntime(
  nativeRuntime: ChatToolRuntime,
  mcpServers: Map<string, McpServerState>,  // connected servers + their tools
): ChatToolRuntime {
  const externalSchemas = flatMap(mcpServers, (server) =>
    server.tools.map(tool => toOpenAISchema(server.id, tool))
  );

  return {
    tools: [...nativeRuntime.tools, ...externalSchemas],
    execute: async (call: ToolCall) => {
      if (call.name.startsWith('mcp_')) {
        return executeMcpTool(call, mcpServers);
      }
      return nativeRuntime.execute(call);
    },
  };
}

This is passed to useChatStreaming.send() as the tools parameter (see useChatStreaming.ts:153), which already accepts ChatToolRuntime | boolean | null. No changes to the streaming hook internals.

3.3 tools/call execution path

async function executeMcpTool(
  call: ToolCall,
  servers: Map<string, McpServerState>,
): Promise<ToolExecutionPayload> {
  const { serverId, toolName } = parseNamespacedName(call.name);
  const server = servers.get(serverId);
  if (!server || !server.sessionId) throw new Error('MCP server not connected');

  const response = await fetch(server.baseUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      ...(server.authHeader ? { 'Authorization': server.authHeader } : {}),
      'Mcp-Session-Id': server.sessionId,
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: nextId(),
      method: 'tools/call',
      params: {
        name: toolName,          // original tool name, not namespaced
        arguments: JSON.parse(call.arguments),
      },
    }),
  });

  const rpc = await response.json();
  if (rpc.error) return { result: rpc.error.message, error: true };
  // MCP tools/call returns { content: ContentPart[] }
  const text = rpc.result.content
    .filter((c: any) => c.type === 'text')
    .map((c: any) => c.text)
    .join('\n');
  return { result: text };
}

Flag gate: the merged runtime is only constructed when localStorage.getItem('lemonade_mcp_client_enabled') === 'true' AND at least one server is connected. Otherwise, DEFAULT_TOOL_RUNTIME is used unchanged.

---

4. Security surface

4.1 Untrusted external tools

External MCP servers are untrusted by default. Risk vectors:

Risk	Mitigation (POC)	Mitigation (future)
Malicious tool output (prompt injection via tool result)	⚠️ Flagged risk — no mitigation in POC. Tool results are passed to the LLM as-is.	Sanitization layer; output length limits; content-type validation.
Tool exfiltrates chat context	⚠️ Flagged risk. The LLM decides what arguments to send.	Tool-permission UX: per-tool allow/deny, argument inspection before send.
Excessive tool calls / DoS	MAX_TOOL_ROUNDS = 5 (existing, useChatStreaming.ts:7) limits rounds.	Per-server rate limiting.
Auth header leakage via XSS	localStorage is same-origin. Desktop webview is single-origin.	Move to SecureStorage (Tauri) or encrypted IndexedDB.

4.2 User consent model (POC)

• Adding a server requires explicit manual entry of URL + optional auth header.
• Each server has an enabled toggle — disabled servers' tools are excluded from the runtime.
• No auto-discovery, no URL redirects, no OAuth flows.
• The feature itself is behind a flag.

4.3 CORS constraints

Platform	CORS situation
Desktop (Tauri webview)	WebView2/WKWebView relaxes CORS for tauri:// origin. Tauri's http plugin or reqwest in Rust can bypass CORS entirely. Recommended: route MCP fetch() through a Tauri command to avoid CORS issues.
Web-app (browser)	Standard browser CORS applies. External MCP server MUST send Access-Control-Allow-Origin headers. If it doesn't, the request fails. This is a known limitation of browser-hosted MCP clients.
Web-app via lemond proxy	Future option: lemond could proxy MCP requests (requires C++ changes — out of scope for POC). Would solve CORS for web-app.

POC approach: use direct fetch(). Document that web-app users may hit CORS errors with servers that don't send CORS headers. Desktop users won't have this issue if we route through Tauri.

---

5. Accessibility & testing expectations

Phase B inherits the WCAG 2.1 AA standard established by the a11y PR stack (A01–A79).

5.1 A11y requirements for MCP UI elements

• Server list: role="list" with aria-label="Registered MCP servers". Each entry: server label, status badge (aria-live="polite" for connection state changes), and action buttons with accessible labels.
• Add server form: proper <label> elements, aria-required on URL field, aria-describedby for auth header help text. Error messages linked via aria-errormessage.
• Tool list (per server): collapsible <details> with <summary> showing tool count. Each tool: name + description.
• Status indicators: color + icon + aria-label (not color alone). "Connected" = green checkmark, "Error" = red exclamation, "Disconnected" = grey dash.
• Focus management: adding a server focuses the new entry. "Connect" button gets focus after error dismissal.
• Keyboard: all actions reachable via Tab/Enter/Space/Escape.

5.2 Testing

New Playwright tests in the a11y.spec.ts suite (continuing the A-number sequence, likely A80+):

Test ID	Description
A80	MCP server list has accessible name and role
A81	Add-server form fields have labels and required indicators
A82	Connection status changes announced via live region
A83	Tool list collapsible with keyboard
A84	Feature flag off → no MCP UI rendered

---

6. What would later require lemond (C++) changes

These are out of scope for Phase B POC but documented for Phase C planning:

Capability	Why it needs lemond	Complexity
MCP proxy endpoint	Web-app CORS bypass: POST /v1/mcp/proxy forwards requests to external MCP servers from the C++ server, avoiding browser CORS restrictions.	Medium — new route in server.cpp, new handler. Must respect quad-prefix (invariant #1).
Server-side MCP client registry	Shared config across all GUI clients (invariant #11 tension — this would be intentional shared state). config.json entry for registered MCP servers.	Medium — config_file.h migration, new CRUD endpoints.
MCP tool → lemonade tool bridging	Exposing external MCP tools as native lemonade MCP tools (tool composition).	High — mcp_server.cpp changes, tool schema merging, forwarding.
SSE transport	Server-Sent Events for long-running tool calls. Needs HTTP/1.1 chunked response support in cpp-httplib.	Medium — cpp-httplib supports SSE but mcp_server.cpp currently returns a single JSON response.
OAuth/PKCE auth flows	Browser-based OAuth requires redirect handling, token storage, refresh.	High — new auth module, secure token storage.

---

7. First Phase B PR — incremental delivery slice

Branch: feat/gui3-mcp-client-poc (off kpoin/ui-testing)
Scope: minimal viable MCP client in GUI3, experimental

Deliverables

1. Feature flag: lemonade_mcp_client_enabled localStorage key. When off, zero code paths execute.

2. New files:

   • src/tools/mcpClient.ts — McpClient class: initialize(), listTools(), callTool(), disconnect. POST-only Streamable HTTP. ~200 lines.
   • src/tools/mcpToolRuntime.ts — buildMergedToolRuntime(), namespacing logic, executeMcpTool(). ~150 lines.
   • src/features/mcp/mcpStore.ts — localStorage CRUD for McpServerEntry[], React state hook useMcpServers(). ~100 lines.
   • src/features/mcp/McpServerPanel.tsx — UI: server list, add/edit/remove/connect/disconnect. Placed in ConnectView. ~250 lines.

3. Modified files:

   • ConnectView.tsx — conditionally render <McpServerPanel /> when flag is on.
   • ChatView.tsx — pass merged runtime to useChatStreaming.send() when MCP servers are connected.

4. No lemond changes. No new npm dependencies. No changes to src/web-app/package.json.

5. Tests: a11y tests A80–A84 (see §5.2). Unit tests for namespacing logic and McpClient (mocked fetch).

6. Docs: brief EXPERIMENTAL.md in prototype docs noting the flag, known limitations (CORS, no SSE, no OAuth, prompt injection risk).

What this PR explicitly does NOT do

• No SSE / streaming transport
• No OAuth / PKCE
• No lemond proxy
• No auto-discovery / templates / marketplace integration
• No deep tool-permission UX (allow/deny per tool)
• No server-side registry

---

@fl0rianr — this is the Phase B design for your review. It's scoped to be purely frontend, flag-gated, and aligned with your binding answers on #2404. Key architectural decision: the ChatToolRuntime interface already supports pluggable tool sets, so we merge external MCP tools into the existing runtime rather than building a parallel execution path. Happy to refine any section. 🍋