Recommended way to expose AionUI WebUI/agent actions as a remote MCP server for ChatGPT/OpenAI?

[Danissimode]

Hi AionUI team,

I’m exploring a safe way to connect AionUI with ChatGPT/OpenAI through a remote MCP gateway.

My target architecture:
ChatGPT / OpenAI remote MCP client
-> HTTPS MCP server on VPS
-> reverse SSH tunnel / VPN
-> local AionUI WebUI on Mac
-> AionUI agents / MCP tools / project workspace

want to keep AionUI local-only, avoid exposing the full WebUI publicly, and expose only a few safe actions through MCP, such as:

• check AionUI health/status
• create a conversation/task
• send a message to a selected assistant/agent
• read conversation/task status
• list or test configured MCP servers

Questions:

1. Is there a stable/documented WebUI HTTP API or WebSocket protocol for external automation?
2. Is external automation through the WebUI API supported, or is it considered internal/private?
3. Is there already a recommended way to expose AionUI itself as an MCP server?
4. Would you recommend building a thin MCP adapter that maps remote MCP tools to AionUI WebUI API/WebSocket calls?
5. Is localhost-only AionUI WebUI + reverse SSH tunnel/VPN + VPS MCP gateway a safe/recommended architecture?

I want to avoid browser UI automation and use a stable API or officially recommended integration path if available.

Thanks!

[skyzhao1223]

Hi @Danissimode — I dug through the current source (AionUi v2.2.2 @ 6744099, and the pinned Rust backend AionCore v0.2.2 @ 47e66d0, which is a separate public repo: iOfficeAI/AionCore) to answer this concretely. Short version up front:

TL;DR: There is a real HTTP REST + WebSocket protocol — it's what the WebUI, the desktop renderer, and the mobile app all talk to — but it is an internal, unversioned contract, not a documented public API. AionUi is an MCP client, not an MCP server; there is no supported "AionUi-as-MCP-server" mode (the MCP servers it does run are internal, for its own agents). A thin MCP adapter over the REST/WS API is technically straightforward — every action you listed has a concrete endpoint — but you must treat it as private API that can break on any release, and your VPS gateway must be the authentication boundary, because in the mode AionUi actually ships, the backend API itself does not require credentials. Your localhost + reverse-tunnel topology is the right shape (it's literally what docs/guides/deploy-server.md suggests), with specific caveats below.

Background: the actual architecture (this changed a lot recently)

Since the 2.x line, the business backend is no longer in the Electron main process. It is aioncore, a Rust binary (Axum 0.8 + Tokio + SQLite, repo iOfficeAI/AionCore, downloaded from its GitHub releases; the version is pinned in AionUi's root package.json as "aioncoreVersion": "v0.2.2"). Every launch path spawns it and talks to it over loopback HTTP + WS:

• Electron main spawns it via packages/web-host/src/backend-launcher.ts (BackendLifecycleManager), always with --local, on 127.0.0.1 and a dynamic port (reported on stdout as AIONCORE_LISTENING {"port":N}; DEFAULT_HOST = "127.0.0.1", DEFAULT_PORT = 25808 in crates/aionui-common/src/constants.rs).
• The renderer calls it directly: packages/desktop/src/common/adapter/httpBridge.ts does REST (fetch → /api/*) plus one WebSocket at /ws carrying JSON frames {name, data}. In Electron, preload injects window.__backendPort; in a browser it uses same-origin URLs.
• Electron IPC (ipcRenderer/ipcMain, single channel ADAPTER_BRIDGE_EVENT_KEY in packages/desktop/src/preload/main.ts) now only carries native bits: window controls, dialogs, theme, update, WebUI lifecycle (packages/desktop/src/process/bridge/*).
• The complete operation→endpoint catalog lives in packages/desktop/src/common/adapter/ipcBridge.ts (~2,500 lines; every httpGet/httpPost/...('/api/...') and wsEmitter('event.name')). Server-side, the contract types live in crates/aionui-api-types ("single source of truth for API contracts" per AionCore's ARCHITECTURE.md).

WebUI mode is served by packages/web-host/src/static-server.ts: a plain Node static server for the SPA that reverse-proxies /api/*, /login, /logout to aioncore and TCP-splices GET /ws (and /api/stt/stream) upgrades to it. It binds 127.0.0.1 by default; it binds 0.0.0.0 only when remote access is explicitly enabled (--remote flag, AIONUI_ALLOW_REMOTE=1, AIONUI_HOST=0.0.0.0, allowRemote in webui.config.json, or the Settings → Remote Connection → WebUI toggle; see docs/guides/webui.md and docs/prds/remote/webui/webui.md). Default port: 25808 production (25809 dev, 25810 multi-instance) — WEBUI_DEFAULT_PORT in packages/desktop/src/common/config/constants.ts. You can start it three ways: AionUi --webui (headless Electron, packages/desktop/src/index.ts), the desktop settings toggle (packages/desktop/src/process/bridge/webuiBridge.ts), or fully without Electron via bun run webui (scripts/webui.ts) / the standalone aionui-web binary (packages/web-cli, one-line installer scripts/install-web.sh). For your Mac-server use case, aionui-web/bun run webui is the cleanest host — no Electron needed.

With that map, your five questions:

1. Is there a stable/documented WebUI HTTP API or WebSocket protocol for external automation?

There is a real protocol; there is no stable, documented public contract. Honest answer: no.

What exists (all verifiable in source):

• REST: /api/* on the WebUI origin (proxied to aioncore). Response envelope { success, data, message? }, errors { success: false, error, code }, pagination { items, total, hasMore } (conventions documented in AionCore's ARCHITECTURE.md).
• WebSocket: a single /ws endpoint; server→client JSON frames { name: "domain.action", data: {...} } (e.g. message.stream, message.userCreated, message.statusChanged, turn.completed, runtime.statusChanged, conversation.listChanged). Client→server WS traffic is minimal (pong, subscribe-show-open, project-explorer fs/scm monitor frames — crates/aionui-realtime/src/handler.rs); actions are done over REST, not WS.
• Auth (when enforced): POST /login (username/password, bcrypt, rate-limited to 5 failures/15 min) sets a JWT aionui-session cookie + HttpOnly refresh cookie; POST /api/auth/refresh; Authorization: Bearer <token> also works (token is returned in the /login response body). WS accepts the token via cookie, Authorization header, or Sec-WebSocket-Protocol (crates/aionui-auth/src/extract.rs).

What does not exist: no OpenAPI spec (grep finds none in either repo), no API versioning, no documented endpoint reference for third parties, no compatibility promise. docs/ covers starting WebUI (docs/guides/webui.md, docs/guides/deploy-server.md) and product behavior (docs/prds/remote/webui/webui.md), never the wire protocol. The protocol moves fast: AionCore v0.2.1 shipped a "⚠ BREAKING CHANGES" section, the whole backend migration (M4–M7 milestones referenced in code comments) happened within recent releases, and CSRF was removed in M6 with a note that it's "slated to return in M7" (httpBridge.ts, resolveCoreCsrfToken() is currently a stub returning ''). Build against it expecting churn; pin your AionUi version and re-check ipcBridge.ts + aionui-api-types after every upgrade.

The one surface explicitly declared "stability": "stable" is the agent-facing helper CLI (aioncore capabilities prints contract agent-facing-aioncore-cli): aioncore config|diagnose|team|session|conversation|skills ... driven by env AIONUI_BASE_URL + AIONUI_RUNTIME_TOKEN. But that token is minted per-conversation and injected into agent subprocesses only (crates/aionui-app/src/commands/cmd_conversation.rs, runtime-token headers x-aionui-runtime-token/x-aionui-user-id/x-aionui-conversation-id in crates/aionui-auth/src/middleware.rs) — it's for agents running inside AionUi, not an integration point for external systems.

2. Is external automation through the WebUI API supported, or internal/private?

Internal/private. The REST+WS API is consumed by first-party clients only: the desktop renderer, the WebUI SPA, the mobile app (mobile/src/services/api.ts — axios + Bearer token — and mobile/src/services/websocket.ts), and the in-process helper CLIs. Nothing in the repo, README, or docs offers it for third-party automation, and there's no statement of support for it.

The supported remote-interaction paths today are:

• WebUI in a browser (human-driven; LAN/cross-network/server deployment documented, incl. SSH tunnels — docs/guides/deploy-server.md).
• Channels — first-party remote control via IM apps: built-in Rust plugins for Telegram, Slack, Discord, Lark, DingTalk, WeChat (crates/aionui-channel/src/plugins/), plus extension channels (WeCom example in examples/ext-wecom-bot). They pair/authorize users, create conversations bound to a chat (create_conversation_for_session in crates/aionui-channel/src/message_service.rs) and drive agents end-to-end; configured under Settings → Remote Connection → Channels (/api/channel/*). If your end goal is "message my AionUi agents from a chat surface", this is the officially built lane — ChatGPT isn't one of the channels, but the pattern shows what "supported remote automation" looks like in this project.

Automation over the raw API will work (it's the same API the SPA uses), but if it breaks in a release you're on your own.

3. Is there a recommended way to expose AionUI itself as an MCP server?

No. Be careful to separate the three MCP roles in the codebase:

• MCP client (yes, core feature): AionUi manages external MCP servers and injects/syncs them into your agents — crates/aionui-mcp (config CRUD /api/mcp/servers, /api/mcp/test-connection, OAuth under /api/mcp/oauth/*, per-agent sync adapters for Claude/Codex/Gemini/Qwen/CodeBuddy/Opencode/Aionrs). This is "MCP Unified Management" in the README.
• Built-in MCP servers for its own agents (stdio, internal): image generation (packages/desktop/src/process/resources/builtinMcp/imageGenServer.ts, uses @modelcontextprotocol/sdk McpServer + StdioServerTransport) and the in-app browser (a launcher wrapping chrome-devtools-mcp, browserServer.ts). These are registered into agent sessions, not exposed to you.
• Team MCP server (internal, loopback): aioncore mcp-team-stdio (built on rmcp, the Rust MCP SDK) is spawned by the ACP agent CLI and forwards to a TeamMcpServer TCP listener bound to 127.0.0.1:0 with token+slot auth (crates/aionui-team/src/mcp/server.rs). Tools are team-collaboration primitives (team_send_message, team_spawn_agent, team_task_create/list/update, team_read_messages, team_members, team_interrupt_agent, …) for Leader/Teammate agents — the README's "built-in Team MCP Server".

None of these is a network-reachable "control AionUi" MCP server, and there is no config flag or documented path to turn AionUi into one. So today: no recommended way exists — which is exactly the gap your proposed adapter would fill. (If you build it, it lives outside AionUi as a gateway, or you could propose it upstream as a feature/extension.)

One caveat if you were hoping to piggyback on the extension system (contributes.webui.apiRoutes in aion-extension.json, as in examples/ext-wecom-bot): those JS route handlers were executed by the legacy Node webserver, which was removed in the M6 backend migration; in the current tree the manifest contributions are parsed and merely listed via GET /api/extensions/webui (crates/aionui-extension/src/manifest.rs, routes.rs), and I found no runtime in aioncore that mounts extension JS handlers (no embedded JS engine in its dependencies). I wouldn't plan an integration around extension API routes right now.

4. Would you recommend building a thin MCP adapter mapping remote MCP tools to AionUI WebUI API/WebSocket calls?

Yes — with eyes open. It's viable, and every action on your list already has a concrete endpoint (client-side names from packages/desktop/src/common/adapter/ipcBridge.ts, server-side routes from the corresponding aioncore crates):

Your MCP tool	AionUi call (verified in source)
health / status	GET /api/auth/status → {success, needs_setup, user_count, is_authenticated} (public, works through the WebUI port). GET /api/system/info → dirs/platform/arch. (GET /health exists but only on the backend's loopback port — the WebUI static server proxies only /api/*, /login, /logout, /ws, /api/stt/stream.)
create conversation/task	POST /api/conversations (CreateConversationRequest: agent type, name, model, assistant, extra — routes in crates/aionui-conversation/src/routes.rs); also /clone, /{id}/fork; team tasks under /api/teams/*
send message to assistant/agent	POST /api/conversations/{id}/messages (SendMessageRequest: content, files, sessions, inject_skills); cancel a turn with POST /api/conversations/{id}/cancel
read conversation/task status	GET /api/conversations/{id} (ConversationResponse incl. status + runtime summary), GET /api/conversations/{id}/messages (history), /messages/latest, /usage; live streaming via WS /ws events message.stream, turn.completed, runtime.statusChanged
list / test MCP servers	GET /api/mcp/servers; POST /api/mcp/test-connection (returns success + discovered tools[], or error/needsAuth + authMethod)

Adapter shape I'd recommend:

• Run the adapter on the Mac, next to AionUi, talking to http://127.0.0.1:25808 (WebUI port) or the backend port directly; expose only the adapter through the tunnel. That keeps AionUi loopback-only and gives you one narrow, tool-whitelisted surface to authenticate.
• Mirror the SPA's behavior: REST for commands, one WS connection to /ws for streaming/status; wrap {success,data} envelopes; unwrap BackendHttpError.code-style error codes (see httpBridge.ts for the exact client semantics — it's effectively a reference implementation you can crib).
• Implement login anyway (POST /login → Bearer token from response body; refresh via POST /api/auth/refresh), even though today's default mode doesn't demand it (see 记录Linux Do佬友们的意见 0808 #5) — it future-proofs you against the M7 auth/CSRF hardening and any move to non-local identity mode.
• Pin the AionUi/aioncore version in your deployment and diff ipcBridge.ts + crates/aionui-api-types on upgrades. Main risks, concretely: protocol churn (breaking changes do ship), auth model in flux (CSRF removed in M6, returning in M7 per code comments), rate limits only on auth routes (login 5/15min — don't hammer it; domain APIs currently unrated), single-instance data-dir guard (a second aioncore on the same data dir exits with BOOTSTRAP_PEER_ALREADY_RUNNING), and WS reconnect semantics (events are a firehose keyed by conversation_id; you re-sync state via REST after realtime.reconnected).

5. Is localhost-only WebUI + reverse SSH tunnel/VPN + VPS MCP gateway safe/recommended?

The topology is sound and matches what the project itself documents — docs/guides/deploy-server.md explicitly lists SSH tunneling (ssh -L 25808:127.0.0.1:25808 …) as the "personal use" remote-access option, and the default bind is loopback. But the safety of your setup hinges on facts about the current auth model that you should know exactly (all from source, v2.2.2 / aioncore v0.2.2):

• Default binding is safe: the WebUI static server binds 127.0.0.1 unless you pass --remote / AIONUI_ALLOW_REMOTE / AIONUI_HOST=0.0.0.0 / the settings toggle (host = allowRemote ? '0.0.0.0' : '127.0.0.1' in packages/web-host/src/static-server.ts); aioncore itself always binds 127.0.0.1 as spawned by AionUi. Keep allowRemote off — with your tunnel you never need it.
• The API is effectively unauthenticated in the shipped configuration. AionUi always spawns aioncore with --local (hard-coded local: true in packages/web-host/src/backend-launcher.ts). In local mode, per crates/aionui-auth/src/middleware.rs and AionCore's ARCHITECTURE.md ("Local Mode … Skips JWT verification, injects a fixed user … Skips CSRF … fully open CORS … WebSocket is also exempt from authentication"), every /api/* domain route and /ws accepts requests without credentials. The WebUI login page is real but it gates the browser UI only — it's enforced via GET /api/auth/user, which is one of the few routes that keeps session auth even in local mode (the auth router builds its own non-local AuthState, crates/aionui-auth/src/routes.rs). Direct curl to /api/conversations etc. doesn't need the password. Local-mode-only admin routes like POST /api/webui/reset-password and /api/auth/internal/* are likewise unauthenticated (they're designed for loopback/desktop use).
• Consequence for your tunnel: anything that can reach the forwarded port can fully control AionUi — and "control AionUi" includes telling agents to run arbitrary commands in your workspace, plus file read/write endpoints (/api/fs/*). So the tunnel endpoint must be treated as root-equivalent on your Mac's agent workspaces: bind ssh -R to the VPS's loopback only (default GatewayPorts no — don't change it), terminate ChatGPT/OpenAI auth at your MCP gateway (the remote-MCP OAuth/bearer layer is your real security boundary), and whitelist the minimum tools in the gateway. Don't put the raw WebUI port on a public interface, ever, in this mode.
• Browser drive-by caveat (worth knowing): in local mode the backend answers with permissive CORS (allow_origin(Any), crates/aionui-app/src/router/routes.rs) and there is currently no CSRF layer. While your WebUI server is running on 127.0.0.1:25808, a malicious web page open in a browser on that Mac can in principle call the local API directly (modern browsers' private-network-access restrictions partially mitigate this). This is inherent to the current local-mode design, not to your tunnel — but it's another reason to keep the surface small and consider running the standalone aionui-web headless instance dedicated to automation, separate from your daily desktop app.
• The hardened mode does exist in the binary — run aioncore without --local (--identity-mode webui, the default) and you get full JWT + CSRF double-submit + credentialed CORS + rate limiting — but AionUi's launchers don't currently expose that path (self-hosters would have to run aioncore manually, cf. the aioncore user subcommand for account bootstrap). If server-grade multi-user auth matters to you, that's a reasonable feature request to file.

Bottom line: yes — localhost-only + reverse tunnel + authenticated VPS MCP gateway is the right architecture given today's code, provided the gateway is the auth boundary and the tunnel stays loopback-bound on the VPS. Build the adapter against REST (/api/conversations…, /api/mcp…) + one /ws subscription, pin versions, and expect to patch it across upgrades since none of this is a public contract. If the maintainers want to chime in on an officially supported automation surface (or a first-party MCP gateway), this thread is a good place for that conversation.

(Versions referenced: AionUi v2.2.2 @ 6744099, AionCore v0.2.2 @ 47e66d0. Everything above was read from source at those commits, not from runtime testing; the codebase moves quickly, so re-verify on newer releases.)