Agent UI MCP Server

Prerequisites: Complete the Setup guide and have the Agent UI backend running.

Overview

The GAIA Agent UI includes a built-in MCP (Model Context Protocol) server that exposes the full Agent UI as a set of tools. This lets external AI assistants — like Claude Code, Cursor, or any MCP-compatible client — interact with GAIA agents, manage chat sessions, index documents, and browse files, all through the same backend that powers the web UI. Conversations initiated via MCP appear in the browser UI in real time, so you can watch tool execution and agent activity as it happens.

Available Tools

Tool	Description
`system_status`	Check GAIA system status (LLM server, model, memory)
`list_sessions`	List all chat sessions with titles and message counts
`create_session`	Create a new chat session
`get_session`	Get details of a specific session
`delete_session`	Delete a session and all its messages
`get_messages`	Get all messages in a session (with agent steps)
`send_message`	Send a message and block until the turn ends (streams to the web UI)
`start_message`	Send a message and return once the backend accepts the turn
`turn_status`	Streaming or idle, the pending permission prompt or question, current step, elapsed time
`wait_for_turn`	Block until the turn is idle, a prompt or question is pending, or the answer contains some text
`answer_prompt`	Answer the pending permission prompt: allow once, always (for the scope shown), or deny
`answer_question`	Answer a question the agent asked mid-turn
`stop_turn`	Stop the running turn, like the Stop button
`turn_view`	The turn as the UI shows it: answer text, activity steps, and the token footer
`turn_metrics`	Steps, tool calls, tokens in and out, and time for the turn
`get_settings`	Active model and provider, and which Lemonade Server GAIA uses
`list_models`	Chat models a provider offers
`set_model`	Pick the model new turns run
`set_model_server`	Switch between GAIA’s Lemonade Server and your own
`list_documents`	List all indexed documents
`index_document`	Index a file for RAG (PDF, TXT, CSV, XLSX, etc.)
`index_folder`	Index all documents in a folder
`browse_files`	Browse files and folders on the filesystem
`search_files`	Search for files by name pattern and type
`preview_file`	Preview file contents or metadata
`take_screenshot`	Capture the Agent UI browser window (Windows)
`memory_stats`	Memory counts and breakdown by category/context/entity
`memory_list`	Filtered list of knowledge rows
`memory_recall`	Hybrid-search recall over the memory store
`memory_get`	Fetch one knowledge row by ID
`memory_get_by_entity`	All rows tagged to an entity (e.g. `person:alice`)
`memory_get_conversation_turns`	Raw turn history for a session
`memory_seed`	Seed knowledge rows directly (for tests/setup)
`memory_clear`	Clear memory rows
`open_session_in_browser`	Open a session in the default browser

get_messages retrieves every page up to the message count reported at the start of the call. Messages added during retrieval are available on the next call. A failed or prematurely empty page returns an explicit error rather than a partial transcript. Existing content and tool-result excerpt limits still apply.

The memory_* tools are conditional. The read tools (memory_stats, memory_list, memory_recall, memory_get, memory_get_by_entity, memory_get_conversation_turns) are registered only when memory MCP access is enabled — either via the Memory Dashboard toggle (mcp_memory_enabled) or GAIA_MEMORY_MCP_ALWAYS=1. The admin tools (memory_seed, memory_clear) additionally require GAIA_MEMORY_ADMIN=1 on the backend process.

Setup with Claude Code

Start the Agent UI backend

# Option 1: Using the startup script (recommended)
# Linux/macOS
./installer/scripts/start-agent-ui.sh

# Windows PowerShell
.\installer\scripts\start-agent-ui.ps1

# Option 2: Manual
uv run python -m gaia.ui.server --debug

Verify the backend is running:

curl http://localhost:4200/api/health

Add the MCP server to Claude Code

# Project-scoped (recommended — only available in this project)
claude mcp add gaia-agent-ui -s project -- uv run python -m gaia.mcp.servers.agent_ui_mcp --stdio

# Or user-scoped (available in all projects)
claude mcp add gaia-agent-ui -s user -- uv run python -m gaia.mcp.servers.agent_ui_mcp --stdio

The --stdio flag tells the MCP server to use stdio transport, which is what Claude Code expects.

Start a new Claude Code conversation

After adding the MCP server, start a new conversation (or restart Claude Code) so it picks up the new tools. You should see gaia-agent-ui tools available.

The MCP server connects to the Agent UI backend at http://localhost:4200 by default. If your backend runs on a different port, pass --backend http://localhost:YOUR_PORT after --stdio.

Setup with Other MCP Clients

The MCP server also supports Streamable HTTP transport for clients that connect over HTTP instead of stdio:

# Start as an HTTP MCP server (default port 8766)
uv run python -m gaia.mcp.servers.agent_ui_mcp

# Custom port
uv run python -m gaia.mcp.servers.agent_ui_mcp --port 9000

Connect your MCP client to http://localhost:8766/mcp.

Usage Examples

Once connected, you can ask Claude Code (or any MCP client) to interact with GAIA:

Chat with the Agent

"Create a new session called 'Project Analysis' and ask the agent
to search for Python files in my project"

Claude Code will call create_session, then send_message, and the conversation will appear in the Agent UI browser window in real time.

Index and Query Documents

"Index all PDFs in my Documents folder and then ask the agent
what the quarterly revenue was"

This calls index_folder to index the documents, then send_message to query them using RAG.

Browse and Search Files

"Search my computer for any Excel spreadsheets related to budgets"

The agent uses search_files to find matching files across the filesystem.

Visual Feedback

"Take a screenshot of the Agent UI so I can see what it looks like"

Captures the browser window and returns the image path for review.

Drive a turn without a browser

send_message blocks until the turn ends, so a turn that stops at a permission prompt never returns. To run a real task unattended, start the turn with start_message, then loop on wait_for_turn(until="attention"). That call returns when the turn finishes or when it needs you. Answer each prompt it reports, then read the result.

import asyncio, json, sys
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server = StdioServerParameters(
        command=sys.executable,
        args=["-m", "gaia.mcp.servers.agent_ui_mcp", "--stdio",
              "--backend", "http://localhost:4200"],
    )
    async with stdio_client(server) as (read, write), ClientSession(read, write) as mcp:
        await mcp.initialize()

        async def call(tool, **args):
            r = await mcp.call_tool(tool, args, read_timeout_seconds=700)
            body = r.structured_content or json.loads(r.content[0].text)
            return body.get("result", body)

        sid = (await call("create_session", title="harness"))["id"]
        await call("start_message", session_id=sid, message="Write 'hello' to notes.txt")
        while True:
            s = await call("wait_for_turn", session_id=sid, until="attention", timeout_ms=600000)
            if s.get("pending_prompt"):
                p = s["pending_prompt"]
                await call("answer_prompt", session_id=sid,
                           confirm_id=p["confirm_id"], decision="allow_once")
            elif s.get("state") == "idle" or s.get("ended"):
                break
            else:
                raise RuntimeError(f"turn needs input: {s}")

        view = await call("turn_view", session_id=sid)
        metrics = await call("turn_metrics", session_id=sid)
        print(view["outcome"], view["content"], view["footer"]["text"])
        print(metrics["steps"], metrics["tool_calls"], metrics["tokens_in"], metrics["tokens_out"])

asyncio.run(main())

turn_view rebuilds the turn from the same events the browser renders. The activity steps are folded the way the UI folds them, and the footer holds the exact numbers the UI shows when you click the line under an answer, e.g. 12.3s · 42.5 tok/s · 123ms TTFT · 1,234 → 56 tokens. Assert on these instead of taking a screenshot. A few details:

turn_status also attaches to a turn the user started in the browser, so its prompts can be answered the same way.
wait_for_turn takes timeout_ms from 1 to 600000. Out-of-range or non-integer values are refused immediately. On timeout it returns timed_out: true with the state the turn had. If the turn ends before the condition, it returns ended: true rather than waiting out the clock.
turn_metrics reports a value nobody measured as null, never 0. tokens_in/tokens_out are the final model call, which is what the UI footer shows. turn_input_tokens/turn_output_tokens cover the whole turn.
Turns started with start_message use the model the Agent UI uses. Change it with set_model.

What answering a prompt can’t do

answer_prompt posts to the same endpoint as the user’s click in the browser, and always names the prompt it answers. It is refused before reaching the backend when:

`refused`	Why
`already_answered`	That prompt was answered already, including by a concurrent call
`stale`	A different prompt is waiting now, or none is
`expired`	The prompt’s own timeout has passed
`wrong_session`	The `confirm_id` belongs to another session
`unknown_prompt`	This server never saw that prompt (no blind answers)
`scope_mismatch`	`always` was sent without repeating the prompt’s `always_scope` exactly
`always_not_offered`	The prompt offers no `always`, so answer `allow_once` or `deny`

The backend checks the confirm_id again, and its rejection comes back as backend_rejected. An always grant covers only the scope the prompt showed, for example write_file on notes.txt, never the whole tool. Over HTTP the server refuses any request that carries a browser Origin header, including pages served from other localhost ports and the Agent UI’s own origin. A web page you visit therefore can’t drive it. MCP clients send no Origin and are unaffected. The backend’s own X-Gaia-UI header and origin checks still apply to every call this server makes. It listens on loopback only. A --host that other machines can reach, such as 0.0.0.0 or a LAN IP, is refused at startup unless you pass --allow-remote and put a bearer token of at least 32 characters in GAIA_AGENT_UI_MCP_TOKEN. Clients then send Authorization: Bearer <token> on every request. A missing or wrong token gets 401. The token is read from the environment, not the command line, and is never logged or echoed.

export GAIA_AGENT_UI_MCP_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
uv run python -m gaia.mcp.servers.agent_ui_mcp --host 0.0.0.0 --allow-remote

Architecture

┌─────────────────┐     stdio/HTTP      ┌──────────────────┐
│  Claude Code /   │ ◄────────────────► │  GAIA Agent UI   │
│  MCP Client      │      MCP tools      │  MCP Server      │
└─────────────────┘                     └────────┬─────────┘
                                                 │ REST API
                                                 ▼
                                        ┌──────────────────┐
                                        │  Agent UI Backend │
                                        │  (FastAPI :4200)  │
                                        └────────┬─────────┘
                                                 │
                                    ┌────────────┼────────────┐
                                    ▼            ▼            ▼
                              ┌──────────┐ ┌──────────┐ ┌──────────┐
                              │ Chat     │ │ RAG      │ │ Lemonade │
                              │ Agent    │ │ Engine   │ │ LLM      │
                              └──────────┘ └──────────┘ └──────────┘

The MCP server is a thin wrapper around the Agent UI REST API. When you call send_message, it streams the response via SSE (Server-Sent Events) from the backend, collects tool outputs and agent steps, and returns the complete result. The web UI receives the same SSE events simultaneously, so you see real-time activity in the browser.

Configuration

Flag	Default	Description
`--stdio`	off	Use stdio transport (for Claude Code)
`--port`	`8766`	HTTP MCP server port
`--host`	`localhost`	HTTP MCP server host
`--allow-remote`	off	Allow a non-loopback `--host`; requires a 32+ character token in `GAIA_AGENT_UI_MCP_TOKEN`
`--backend`	`http://localhost:4200`	Agent UI backend URL

Removing the MCP Server

claude mcp remove gaia-agent-ui

Troubleshooting

MCP tools not appearing in Claude Code

Make sure you started a new conversation after adding the MCP server. Claude Code only loads MCP tools at conversation start. Also verify the backend is running with curl http://localhost:4200/api/health.

'Cannot connect to GAIA backend' errors

The Agent UI backend must be running before the MCP server can work. Start it with uv run python -m gaia.ui.server or use the startup scripts in installer/scripts/.

send_message times out

Large documents or complex queries can take time. The default timeout is 180 seconds. If the Lemonade LLM server is slow to respond, check its status with system_status. A turn that is waiting on a permission prompt never finishes on its own. Use start_message and answer_prompt instead (see Drive a turn without a browser).

403 'Invalid Origin header' over HTTP

The server refuses requests that carry a browser Origin, so a web page can’t answer prompts. Connect from an MCP client (Claude Code, the Python SDK), or use --stdio.

Getting Started

C++ Framework

Python Framework

Agent UI MCP Server

Overview

Available Tools

Setup with Claude Code

Setup with Other MCP Clients

Usage Examples

Chat with the Agent

Index and Query Documents

Browse and Search Files

Visual Feedback

Drive a turn without a browser

What answering a prompt can’t do

Architecture

Configuration

Removing the MCP Server

Troubleshooting

​Overview

​Available Tools

​Setup with Claude Code

​Setup with Other MCP Clients

​Usage Examples

​Chat with the Agent

​Index and Query Documents

​Browse and Search Files

​Visual Feedback

​Drive a turn without a browser

​What answering a prompt can’t do

​Architecture

​Configuration

​Removing the MCP Server

​Troubleshooting

Overview

Available Tools

Setup with Claude Code

Setup with Other MCP Clients

Usage Examples

Chat with the Agent

Index and Query Documents

Browse and Search Files

Visual Feedback

Drive a turn without a browser

What answering a prompt can’t do

Architecture

Configuration

Removing the MCP Server

Troubleshooting