noui generate mcp
- Repo stars 0
- Author repo skills-registry
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Env read
- Network behavior
- External requests
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
Output: Note the `server_id` of the server you want to manage.
Spawns the server process in the background. Logs go to: 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.
For servers that use CDP (Akamai-protected sites like Expedia), status also shows browser session health:
Sends SIGTERM and clears the PID file.
Add the server to `~/.claude.json` under `mcpServers`. Claude Code launches the server process automatically via `command` + `args`. Concrete example (replace paths with your actual noui directory): 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.
# 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>` |
---
> Source: [adoptai/noui](https://github.com/adoptai/noui) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
Listed in source order.
sections -> Critical Rules (Never Violate) → Step 1 — List Available Servers → Step 2 — Start a Server → Step 3 — Check Server Status → Step 4 — Stop a Server → Step 5 — Connect to Claude Code
terms -> Prerequisite · How requests are executed · ALWAYS · NEVER · not · API.md · Concrete example · restart Claude Code
files/cmd -> /noui-record-workflow · workbench/mcp_servers/<app_slug>/<server_id>/ · noui/ · .venv/bin/python cli/main.py · workbench/mcp_servers/ · fetch(..., {credentials: 'include'}) · --execution-mode http · mcp list
body sha256 -> 975a9e9cb68a
Critical Rules (Never Violate)
ALWAYS run
mcp listfirst to get the exactserver_idbefore any other command NEVER editserver.pyormanifest.jsondirectly — regenerate by re-runningworkflow export --as mcpWhen adding to~/.claude.json, ALWAYS use the absolute path to.venv/bin/python— not the systempythonorpython3ALWAYS restart Claude Code after editing~/.claude.json— the config is read at startup You do not need to runmcp startseparately when using the~/.claude.jsonstdio config — Claude Code launches the process automaticallyStep 1 — List Available Servers
Output: Note the
server_idof the server you want to manage.Step 2 — Start a Server
Spawns the server process in the background. Logs go to: 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
For servers that use CDP (Akamai-protected sites like Expedia), status also shows browser session health:
Step 4 — Stop a Server
Sends SIGTERM and clears the PID file.