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

Command	Purpose
.venv/bin/python cli/main.py mcp list	List all generated servers with running status
.venv/bin/python cli/main.py mcp start <server_id>	Start a server process in the background
.venv/bin/python cli/main.py mcp stop <server_id>	Stop a running server process
.venv/bin/python cli/main.py mcp status <server_id>	Show running state, tool count, manifest path, and CDP reachability (for browser-based servers)
.venv/bin/python cli/main.py mcp docs <server_id>	Regenerate API.md from current tools.json
.venv/bin/python cli/main.py mcp docs <server_id> --check	Exit non-zero if API.md is stale (for CI / agent validation)
.venv/bin/python cli/main.py mcp verify <server_id>	Run AuthVerifier — reports PASS / REPAIR_APPLIED / NEEDS_SECRET / UNSUPPORTED
.venv/bin/python cli/main.py mcp diagnose-auth <server_id>	Full auth diagnosis: strategy, env var status, per-step verification, repair suggestions

---

Troubleshooting

Symptom	Fix
mcp list shows no servers	No workflows exported yet — run /noui-record-workflow first
MCP server '<id>' not found	Run mcp list to get the exact server_id string
Server crashes immediately	Check .mcp-<server_id>.log in the server dir for Python errors
Stale PID (shows running but is not)	mcp stop <server_id> clears stale PID; then mcp start again
Claude Code does not see tools after adding to config	Confirm absolute paths are correct; restart Claude Code; run /noui-generate-mcp to verify connection
server.py not found error	Re-run workflow export --as mcp for that session to regenerate the server
Auth errors at runtime (authenticated server)	Run mcp diagnose-auth <server_id> — shows missing env vars and repair steps
NEEDS_SECRET <VAR> from verify	Set <VAR>=<value> in noui/.env and re-run mcp verify <server_id>
Server is v1 (no auth_plan.json)	Re-export with workflow export --as mcp ... --profile-slug <slug> --verify to upgrade to v2
Tool fails with "All connection attempts failed"	CDP-based server needs browser session — run mcp status <server_id> to check CDP, then noui tabby session ensure
Tabby session shows HEALTHY but tools still fail	Worker crashed but DB state is stale — run noui tabby session ensure (auto-detects and restarts dead workers)
Exported server has profile_slug: null	No --profile-slug was passed at export time — re-export: workflow export --as mcp <session_id> --profile-slug <slug>