Agent UI MCP Server: programmatic UI control for agents

[kovtcharov]

Summary

Create an MCP server that wraps the Agent UI REST API so the agent can programmatically control the UI — search past conversations, create sessions, manage tunnels, and manage schedules. This is the agent's interface to the UI, not direct database access.

Source Spec

docs/plans/autonomous-agent-infrastructure.md — Milestone 2

Why MCP (Not Direct DB Access)

The Agent UI owns its database (gaia_chat.db). The agent never touches it directly. Instead, the MCP server wraps REST API endpoints as MCP tools, giving the agent a clean, stable interface.

MCP Tools

Session Management

• list_sessions(limit, offset) — List chat sessions with title, date, message count
• create_session(title, model, system_prompt) — Create a new session
• get_session(session_id) — Get session details
• update_session(session_id, title, system_prompt) — Update session
• delete_session(session_id) — Delete session and messages

Conversation Access

• get_session_messages(session_id, limit) — Get messages for a session
• search_conversations(query, limit) — FTS across all sessions (NEW endpoint)
• export_session(session_id, format) — Export as markdown/JSON

Tunnel Management

• start_tunnel() — Start ngrok tunnel, return URL + auth token
• stop_tunnel() — Stop active tunnel
• get_tunnel_status() — Check tunnel status

System

• get_system_status() — Health, uptime, model info

Implementation

• FastMCP server calling Agent UI REST API internally (localhost:4200)
• New GET /api/sessions/search endpoint in Agent UI for conversation FTS
• Runs alongside Agent UI backend

Files

src/gaia/ui/mcp_server.py          # FastMCP server
src/gaia/ui/routers/sessions.py    # Extended: add search endpoint
tests/unit/test_agent_ui_mcp.py
tests/integration/test_agent_ui_mcp_e2e.py

Dependencies

• v0.17.0 Agent UI must be shipped first

Acceptance Criteria

• FastMCP server with all session/tunnel/system tools
• Conversation search endpoint with FTS
• Agent can search past conversations via MCP
• Graceful error when Agent UI is not running
• Unit tests (mocked HTTP) + integration tests (running Agent UI)