NoUI MCP Server Lifecycle

Manage generated FastMCP servers and connect them to Claude Code. Servers are generated by /noui-record-workflow and live under workbench/mcp_servers/<app_slug>/<server_id>/.

All commands run from the noui/ directory using .venv/bin/python cli/main.py.

Prerequisite: At least one server must exist under workbench/mcp_servers/. Run /noui-record-workflow first if none exist.

How requests are executed: by default, each tool opens a WebSocket to Tabby's CDP endpoint and runs fetch(..., {credentials: 'include'}) inside the authenticated browser. A live Tabby session with the target site open is required at invocation time. See /noui-record-workflow → How Execution Works for the full explanation and the --execution-mode http escape hatch.

Critical Rules (Never Violate)

• ALWAYS run mcp list first to get the exact server_id before any other command
• NEVER edit server.py or manifest.json directly — regenerate by re-running workflow export --as mcp
• When adding to ~/.claude.json, ALWAYS use the absolute path to .venv/bin/python — not the system python or python3
• ALWAYS restart Claude Code after editing ~/.claude.json — the config is read at startup
• You do not need to run mcp start separately when using the ~/.claude.json stdio config — Claude Code launches the process automatically

Every generated server folder includes an API.md file — a human-readable API reference for all tools. Read it to understand a server's tools without inspecting tools.json or operation files. Refresh it with mcp docs <server_id> after any edit to tools.json.

Step 1 — List Available Servers

.venv/bin/python cli/main.py mcp list

Output:

MCP servers:

  SERVER ID                        APP                  TOOLS  STATUS
  -----------------------------------------------------------------------
  hubspot-create-contact-abc12345  HubSpot                  3  stopped
  jsonplaceholder-test-3ab1cc83    Jsonplaceholder Test      2  running (PID 46929)

Note the server_id of the server you want to manage.

Step 2 — Start a Server

.venv/bin/python cli/main.py mcp start <server_id>

Spawns the server process in the background. Logs go to:

workbench/mcp_servers/<app_slug>/<server_id>/.mcp-<server_id>.log

MCP stdio servers exit immediately when there is no connected client — this is expected. The server is not meant to run continuously standalone; it is launched on-demand by the client.

Step 3 — Check Server Status

.venv/bin/python cli/main.py mcp status <server_id>

For servers that use CDP (Akamai-protected sites like Expedia), status also shows browser session health:

  CDP       : ✓ reachable (localhost:9222)   ← worker is running
  CDP       : ✗ not reachable (localhost:9222) ← run: noui tabby session ensure

Step 4 — Stop a Server

.venv/bin/python cli/main.py mcp stop <server_id>

Sends SIGTERM and clears the PID file.

Step 5 — Connect to Claude Code

Add the server to ~/.claude.json under mcpServers. Claude Code launches the server process automatically via command + args.

{
  "mcpServers": {
    "<server_id>": {
      "type": "stdio",
      "command": "/absolute/path/to/noui/.venv/bin/python",
      "args": [
        "/absolute/path/to/noui/workbench/mcp_servers/<app_slug>/<server_id>/server.py"
      ]
    }
  }
}

Concrete example (replace paths with your actual noui directory):

{
  "mcpServers": {
    "jsonplaceholder-test-3ab1cc83": {
      "type": "stdio",
      "command": "/home/gabriel/Documents/adopt/noui/.venv/bin/python",
      "args": [
        "/home/gabriel/Documents/adopt/noui/workbench/mcp_servers/jsonplaceholder-test/jsonplaceholder-test-3ab1cc83/server.py"
      ]
    }
  }
}

After saving, restart Claude Code. The tools defined in the server will be available in Claude Code's tool list. You can verify by running /noui-generate-mcp in Claude Code.

Decision Flow

Start
  │
  ├─ Need to see what servers exist?
  │     └─ Step 1: mcp list
  │
  ├─ Auth not working / not sure if server is ready?
  │     ├─ mcp verify <server_id>      → PASS / NEEDS_SECRET / REPAIR_APPLIED
  │     └─ mcp diagnose-auth <server_id> → full breakdown with repair suggestions
  │
  ├─ Need to run a server standalone (test/debug)?
  │     ├─ Step 2: mcp start <server_id>
  │     ├─ Step 3: mcp status <server_id>
  │     └─ Step 4: mcp stop <server_id>
  │
  └─ Need to use tools from Claude Code?
        └─ Step 5: add to ~/.claude.json → restart Claude Code
               └─ Verify: /mcp in Claude Code shows the server

CLI Command Reference

Troubleshooting

Source: adoptai/noui — distributed by TomeVault.