# How TUUI Manages Remote MCP Servers with Cloudflare mcp-remote Integration

> Discover how TUUI manages remote MCP servers using Cloudflare mcp-remote integration. Learn to establish SSE tunnels for seamless remote connectivity with this powerful solution.

- Repository: [AIQL/tuui](https://github.com/ai-ql/tuui)
- Tags: how-to-guide
- Published: 2026-02-23

---

**TUUI treats every MCP server as a client-side API object exposed through the preload bridge (`window.mcpServers`), using the Cloudflare `mcp-remote` package to establish SSE tunnels for remote connectivity.**

The [ai-ql/tuui](https://github.com/ai-ql/tuui) repository implements a unified architecture where remote Model Context Protocol (MCP) servers are configured via JSON and proxied through Cloudflare's `mcp-remote` helper. This design allows the renderer process to interact with remote hosts without direct network access, abstracting all transport complexity behind a consistent JavaScript API.

## Configuration Architecture

Remote MCP servers are defined in [`src/main/assets/config/mcp.json`](https://github.com/ai-ql/tuui/blob/main/src/main/assets/config/mcp.json) using a command-based configuration pattern. The **MCP launcher** reads these definitions and initializes the `mcp-remote` process to establish connectivity.

```json
{
  "mcpServers": {
    "cloudflare": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://YOURDOMAIN.com/sse"]
    }
  }
}

```

- The `command` and `args` array specify that `npx` should execute the `mcp-remote` package.
- The **MCP config loader** ([`src/main/mcp/config.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/mcp/config.ts)) parses this configuration and spawns the process.
- `mcp-remote` opens a **Server-Sent Events (SSE)** tunnel to the Cloudflare worker endpoint, proxying all subsequent MCP calls (tools, prompts, resources) through that secure channel.

The main process automatically watches [`mcp.json`](https://github.com/ai-ql/tuui/blob/main/mcp.json) for changes using `fs.watch` and reloads the configuration dynamically without requiring an application restart.

## Loading and Exposing Remote Servers

The integration relies on a **preload bridge** pattern to safely expose remote server capabilities to the renderer process.

In the main process, `loadConfigFile` (defined in [`src/main/mcp/config.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/mcp/config.ts)) parses the JSON configuration and returns a map of `McpServerConfig` objects. The **preload script** ([`src/preload/index.ts`](https://github.com/ai-ql/tuui/blob/main/src/preload/index.ts)) then constructs the `window.mcpServers` API by:

1. Calling `listClients` via IPC to retrieve locally-run MCP servers.
2. Merging these with the remote definitions from the configuration.
3. Exposing the unified list through `window.mcpServers.get()`.

This approach ensures that remote servers appear as first-class citizens alongside local stdio-based servers, with both accessible through the same interface.

## Store Integration and UI Consumption

The renderer-side state management handles server discovery and method invocation through [`src/renderer/store/mcp.ts`](https://github.com/ai-ql/tuui/blob/main/src/renderer/store/mcp.ts).

- `getRawServers()` retrieves the raw configuration object from `window.mcpServers?.get()`.
- `getServers()` merges remote definitions with any local stdio servers, returning the final map used by UI components.
- Components like **McpSideDrawer** and the **Prompt** store consume this map to list available primitives and invoke remote methods.

When users select a remote server in the interface, `useMcpStore` persists the selection and makes the server's methods available for subsequent calls.

## Remote Call Flow

When the UI initiates an MCP operation against a remote server, the request flows through several abstraction layers:

1. **Selection**: The user chooses a remote server (e.g., "cloudflare") via the UI, stored in `useMcpStore`.
2. **Method Resolution**: `getServerFunction` locates the appropriate method (e.g., `prompts.list`) on the server object.
3. **Transport**: The method execution is delegated to the `mcp-remote` process, which serializes the JSON-RPC request and transmits it over the Cloudflare SSE channel.
4. **Response Handling**: The remote worker's response returns through the same tunnel, is parsed by `mcp-remote`, and passed back to the renderer as a standard JavaScript object.

Because all transport logic is encapsulated behind the `MCPAPI` interface, UI components remain agnostic to whether they are calling a local CLI tool or a remote Cloudflare worker.

## Code Examples

### Adding a Cloudflare Remote Server

Edit [`src/main/assets/config/mcp.json`](https://github.com/ai-ql/tuui/blob/main/src/main/assets/config/mcp.json) to include the remote endpoint:

```json
{
  "mcpServers": {
    "cloudflare": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://example.com/sse"]
    }
  }
}

```

The main process detects the file change automatically and reloads the server list.

### Listing Primitives from a Remote Server

Access remote prompts or tools through the MCP store:

```typescript
import { useMcpStore } from '@/renderer/store/mcp'

async function listRemotePrompts() {
  const mcpStore = useMcpStore()
  
  // Ensure the server list is current
  await mcpStore.updateServers?.()
  
  // Access the remote server by its configuration key
  const server = mcpStore.getServers?.()['cloudflare']
  if (!server) throw new Error('Remote server not found')
  
  // Invoke the prompts.list primitive
  const prompts = await server.prompts?.list({ method: 'prompts/list' })
  console.log(prompts)
}

```

The call traverses the Cloudflare SSE tunnel managed by the `mcp-remote` process.

### Refreshing the Server List

Trigger a configuration reload after manual edits:

```typescript
await window.mcpServers?.refresh()

```

This invokes the preload script's `refreshAPI` function, which re-queries the main process for updated client lists and remote definitions.

## Summary

- **Configuration-driven**: Remote servers are defined in [`src/main/assets/config/mcp.json`](https://github.com/ai-ql/tuui/blob/main/src/main/assets/config/mcp.json) using `npx mcp-remote` commands.
- **Unified API**: The preload bridge ([`src/preload/index.ts`](https://github.com/ai-ql/tuui/blob/main/src/preload/index.ts)) exposes all servers through `window.mcpServers`, hiding transport differences.
- **SSE Tunneling**: Cloudflare's `mcp-remote` establishes Server-Sent Events connections, proxying JSON-RPC traffic securely.
- **Dynamic Reloading**: File watchers in [`src/main/mcp/config.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/mcp/config.ts) enable hot-reloading of server configurations without app restarts.
- **Store Abstraction**: [`src/renderer/store/mcp.ts`](https://github.com/ai-ql/tuui/blob/main/src/renderer/store/mcp.ts) merges remote and local servers, providing a consistent interface for UI components.

## Frequently Asked Questions

### How does TUUI handle authentication for remote MCP servers?

TUUI delegates authentication to the `mcp-remote` process. Since `mcp-remote` manages the SSE connection to the Cloudflare worker, any authentication tokens or headers are handled at the Cloudflare layer or within the `mcp-remote` package configuration, keeping the TUUI renderer process unburdened by credential management.

### Can TUUI mix local stdio servers with remote Cloudflare servers simultaneously?

Yes. The `getServers()` method in [`src/renderer/store/mcp.ts`](https://github.com/ai-ql/tuui/blob/main/src/renderer/store/mcp.ts) specifically merges remote definitions from `window.mcpServers.get()` with local stdio-based clients, allowing UI components to interact with both types through identical APIs without distinguishing between transport mechanisms.

### What happens if the Cloudflare SSE connection drops?

The `mcp-remote` process manages connection lifecycle and reconnection logic. From TUUI's perspective, if the remote server becomes unreachable, the corresponding methods will throw errors that can be caught by the store or UI components, while the application continues functioning with other available servers.

### Where is the server configuration cached in TUUI?

The raw configuration is read from [`src/main/assets/config/mcp.json`](https://github.com/ai-ql/tuui/blob/main/src/main/assets/config/mcp.json) by `loadConfigFile` in [`src/main/mcp/config.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/mcp/config.ts), but it is not persistently cached in the renderer. Each call to `window.mcpServers.get()` or `refresh()` retrieves the current state from the main process, ensuring the UI always reflects the latest configuration file contents.