noui-generate-mcp

name	noui-generate-mcp
description	Use this skill when the user wants to start, stop, check, or list generated NoUI MCP servers, or connect a server to Claude Code. Triggers on "start the MCP server", "run noui mcp", "connect to Claude Code", "add to mcpServers", "noui mcp start", "noui mcp list", "noui mcp status", "how do I use the generated server", or "I want to call this tool from Claude".

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>