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

```bash
.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

```bash
.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

```bash
.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

```bash
.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`.

```json
{
  "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):

```json
{
  "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>` |