# WebMCP for app.not24get.me

Agent and operator skill for configuring, using, and troubleshooting the not24get WebMCP
integration at `https://app.not24get.me`.

**Audience:** Cursor / Claude Desktop operators, support engineers, and AI agents that drive
the `webmcp-local-relay` MCP server.

**Related user docs:**

- [Connect Web MCP](/user-manual/web-mcp/connect-web-mcp)
- [Available tools](/user-manual/web-mcp/available-tools)

---

## 1. What WebMCP does

WebMCP lets an MCP host (Cursor, Claude Desktop, or an MCP browser extension) call
allow-listed tools against the **browser tab where you are signed in**. There is no separate
API token — tool calls use the same session cookies as the open app.

Three parties must agree on **one** relay endpoint (`ws://127.0.0.1:9333` by default):

```text
┌─────────────────┐     WebSocket      ┌──────────────────┐     WebSocket      ┌─────────────────┐
│  MCP host       │ ◄────────────────► │  Local Agent     │ ◄────────────────► │  app.not24get   │
│  (Cursor, etc.) │   relay client     │  relay (server)  │   browser source │  .me tab        │
└─────────────────┘                    └──────────────────┘                    └─────────────────┘
```

The app tab registers tools when you click **Connect to Local Agent** in the WebMCP panel
(sparkle button, bottom-right on desktop widths ≥ 768px).

---

## 2. Quick health check

Run these **before** deep debugging. Most failures are visible here.

### 2.1 In the app tab

| Check                        | Healthy                       | Unhealthy                           |
| ---------------------------- | ----------------------------- | ----------------------------------- |
| WebMCP panel                 | **Connected via Local Agent** | Disconnected, error, or disabled    |
| Diagnostics → Relay endpoint | `ws://127.0.0.1:9333`         | Wrong port or missing               |
| Diagnostics → Connect state  | `connected`                   | `disconnected`, `error`, `disabled` |
| Signed in                    | Bookmark hub loads            | Redirect to login                   |

### 2.2 On your machine (terminal)

```bash
# Relay listening on 9333?
lsof -iTCP:9333 -sTCP:LISTEN

# Browser tab connected to relay?
lsof -iTCP:9333 | rg firefox|chrome|Chromium

# Stale port file (must match listening port)?
cat ~/.webmcp/relay-port.json

# Zombie relay processes (should be 0–2, not many)?
ps aux | rg webmcp-local-relay | rg -v rg
```

### 2.3 In the MCP host (Cursor)

| Check                       | Healthy                      | Unhealthy         |
| --------------------------- | ---------------------------- | ----------------- |
| `webmcp-local-relay` server | Enabled (green)              | Disabled or error |
| `webmcp_list_sources`       | `count: 1` (or more)         | `count: 0`        |
| `webmcp_list_tools`         | 6+ `not24getme_tool_*` tools | `count: 0`        |

If the MCP panel lists tools but `webmcp_list_sources` returns **0**, see
[§4.2 Port split](#42-port-split-browser-on-9333-cursor-on-9334).

---

## 3. Setup from zero

### 3.1 Prerequisites

- Signed-in session at `https://app.not24get.me` (or local dev on `http://localhost:5173`).
- Secure context: HTTPS or localhost.
- Viewport width ≥ 768px (WebMCP is hidden on small screens).
- Chromium-based browser or Firefox with relay support.

### 3.2 Start a single Local Agent relay

**One** relay process must own port **9333**. Do not leave old relays running.

```bash
# Optional: clear zombies first (see §5 Clean reset)
npx -y @mcp-b/webmcp-local-relay@latest --host 127.0.0.1 --port 9333
```

Or let Cursor spawn it via MCP config (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "webmcp-local-relay": {
      "command": "npx",
      "args": ["-y", "@mcp-b/webmcp-local-relay@latest"]
    }
  }
}
```

Toggle the server **off then on** in Cursor after killing stale processes.

### 3.3 Connect the app tab

1. Open a workspace, e.g. `https://app.not24get.me/workspaces/<id>`.
2. Open the **WebMCP** panel (sparkle FAB, bottom-right).
3. Click **Connect to Local Agent**.
4. Confirm **Connected via Local Agent** and relay endpoint `ws://127.0.0.1:9333`.

### 3.4 Verify from MCP

```text
webmcp_list_sources   → count ≥ 1, origin https://app.not24get.me
webmcp_list_tools     → not24getme_tool_folder_list, bookmark_create, etc.
```

### 3.5 Smoke-test a tool

```text
not24getme_tool_workspace_list  {}
```

or

```text
not24getme_tool_folder_list  { "workspaceId": "<workspace-id>" }
```

A healthy call returns JSON in under a few seconds. A **25s timeout** means the browser
source is not responding — see [§4.3](#43-tool-invocations-timeout-after-25-seconds).

---

## 4. Troubleshooting decision tree

Start at your **symptom**. Each section lists cause → fix.

### 4.1 "Unable to connect to WebMCP relay at ws://127.0.0.1:9333"

**Cause:** Nothing is listening on 9333, or a firewall blocks loopback WebSockets.

**Fix:**

1. Start the relay (§3.2).
2. Confirm: `lsof -iTCP:9333 -sTCP:LISTEN` shows one `node` process.
3. Ensure `~/.webmcp/relay-port.json` says `"port": 9333` (edit if stale `9334`).
4. In the app, click **Connect to Local Agent** again.

---

### 4.2 Port split: browser on 9333, Cursor on 9334

**Symptoms:**

- App shows **Connected via Local Agent**.
- Cursor MCP card lists `not24getme_tool_*` tools (cached).
- `webmcp_list_sources` returns **`count: 0`**.
- Direct tool calls fail with `Tool not found`.

**Cause:** An old relay process held port 9333. When Cursor started a new relay, it bound to
**9334** and wrote that to `~/.webmcp/relay-port.json`. The browser still talks to the zombie
on **9333**; Cursor talks to **9334**. They never meet.

**Fix:**

1. Kill **all** relay processes:

   ```bash
   pkill -f webmcp-local-relay
   sleep 2
   lsof -iTCP:9333  # must be empty
   lsof -iTCP:9334  # must be empty
   ```

2. Reset port file:

   ```json
   {"port": 9333, "host": "127.0.0.1"}
   ```

   Path: `~/.webmcp/relay-port.json`

3. Start **one** relay on 9333 (§3.2) **or** toggle Cursor MCP server off/on.
4. **Disconnect** in the app, reload the tab, **Connect to Local Agent** again.
5. Confirm `webmcp_list_sources` shows `count: 1`.

**Prevention:** After reboot or long idle sessions, run `pkill -f webmcp-local-relay` before
starting Cursor or the app.

---

### 4.3 Tool invocations timeout after 25 seconds

**Symptoms:**

- Sources and tools appear connected.
- Every `not24getme_tool_*` call ends with:
  `Proxied invocation for tool "..." timed out after 25000ms`.

**Common causes:**

| Cause                            | How to tell                                 | Fix                           |
| -------------------------------- | ------------------------------------------- | ----------------------------- |
| Port split (§4.2)                | `list_sources` = 0 while app says connected | §4.2 clean reset              |
| Tab closed or sleeping           | No browser socket on 9333                   | Reopen tab, reconnect         |
| Not signed in                    | API returns 401 inside tool                 | Sign in, reconnect            |
| Stale tab without invoke handler | Tools listed but invoke never returns       | Disconnect, reload, reconnect |
| Multiple tabs (see §4.4)         | Several suffixed tools; wrong tab targeted  | Close extra tabs, keep one    |

**Advanced:** The relay only accepts tool results in `{ type: "result", callId, result: {...} }`
form. Error payloads must use `result.isError: true`. Older app builds that sent a top-level
`error` field caused silent drops and 25s timeouts even for simple "tool not found" cases.
Ensure you run a current app build if timeouts persist after §4.2.

---

### 4.4 Tool names with tab suffixes (`_6b61`, `_e168`, …)

**Symptoms:**

- `webmcp_list_tools` shows `not24getme_tool_folder_list_a1b2` instead of
  `not24getme_tool_folder_list`.
- Calls to the unsuffixed name fail.

**Cause:** Multiple browser tabs connected to the relay with the same tool names. The relay
disambiguates with a 4-character tab suffix.

**Fix:**

1. Close extra `app.not24get.me` tabs.
2. Keep **one** tab connected.
3. Disconnect and reconnect in that tab.
4. Tool names should return to unsuffixed form (6 tools).

When multiple tabs are intentional, call the **suffixed** name shown in `webmcp_list_tools`.

---

### 4.5 MCP error: Tool not found

**Symptoms:**

- `MCP error -32602: Tool not24getme_tool_folder_list not found`
- Cursor tool list empty despite enabled server

**Cause:** MCP host not connected to the same relay as the browser, or no browser source
registered.

**Fix:**

1. Complete §4.2 clean reset if needed.
2. Confirm browser connected: `lsof -iTCP:9333` shows browser → 9333.
3. Toggle Cursor `webmcp-local-relay` MCP server off/on.
4. Reconnect app tab.

---

### 4.6 "No usable navigator.modelContext" / extension path fails

**Symptoms:** **Connect to Browser Extension** fails; banner mentions `mcp_extension_unavailable`.

**Fix:** Use **Connect to Local Agent** instead (recommended for Cursor). Extension path needs
MCP-B or Chrome 146+ with `chrome://flags/#enable-webmcp-testing`.

---

### 4.7 WebMCP disabled or not visible

| Message                        | Cause                                | Fix                                              |
| ------------------------------ | ------------------------------------ | ------------------------------------------------ |
| WebMCP is disabled             | `ENABLE_WEB_MCP` false in production | Expected on some envs; enabled in dev by default |
| Not available on small screens | Viewport &lt; 768px                  | Widen window or use tablet/desktop               |
| Panel missing                  | Not signed in                        | Sign in to bookmark hub                          |

---

## 5. Clean reset procedure

Use this when anything is "stuck" after the checks above.

```bash
# 1. Stop all relays
pkill -f webmcp-local-relay
sleep 2

# 2. Verify ports free
lsof -iTCP:9333 || echo "9333 free"
lsof -iTCP:9334 || echo "9334 free"

# 3. Fix port file
printf '%s\n' '{"port":9333,"host":"127.0.0.1"}' > ~/.webmcp/relay-port.json

# 4. Start one relay (pick one approach)
npx -y @mcp-b/webmcp-local-relay@latest --host 127.0.0.1 --port 9333 &
# OR toggle webmcp-local-relay off/on in Cursor MCP settings

# 5. In browser: close extra app tabs, reload one workspace tab
# 6. WebMCP panel → Disconnect → Connect to Local Agent
# 7. In Cursor: webmcp_list_sources → count must be ≥ 1
```

---

## 6. Allow-listed tools (v1)

In-app IDs use dots; MCP clients usually see underscores.

| In-app ID                         | MCP name (typical)                | Purpose                          |
| --------------------------------- | --------------------------------- | -------------------------------- |
| `not24getme.tool.workspace.list`  | `not24getme_tool_workspace_list`  | List workspaces                  |
| `not24getme.tool.folder.list`     | `not24getme_tool_folder_list`     | List folders                     |
| `not24getme.tool.folder.create`   | `not24getme_tool_folder_create`   | Create folder (`name` required)  |
| `not24getme.tool.bookmark.search` | `not24getme_tool_bookmark_search` | Search (`query` required)        |
| `not24getme.tool.bookmark.create` | `not24getme_tool_bookmark_create` | Create bookmark (`url` required) |
| `not24getme.tool.bookmark.delete` | `not24getme_tool_bookmark_delete` | Delete bookmark                  |

**Workspace resolution:** Omit `workspaceId` to use the workspace in the current URL, then
the account default.

**Bookmark create** mirrors the in-app form: `title`, `description`, `tags[]`, `folderName` or
`folderId`, `archiveCapture`, `workspaceId`.

---

## 7. Example agent workflows

### List folders in Demo workspace

```json
{
  "workspaceId": "6a46a7ca7332c018c82ccf4d"
}
```

Tool: `not24getme_tool_folder_list`

### Create a demo folder

```json
{
  "name": "Enterprise Search Pain Points",
  "workspaceId": "6a46a7ca7332c018c82ccf4d"
}
```

Tool: `not24getme_tool_folder_create`

### Create a bookmark with details

```json
{
  "url": "https://www.nngroup.com/articles/intranet-information-architecture/",
  "title": "NN/g: Intranet information architecture",
  "description": "Demo link for enterprise findability gaps.",
  "tags": ["intranet", "findability", "demo"],
  "folderName": "Enterprise Search Pain Points",
  "workspaceId": "6a46a7ca7332c018c82ccf4d",
  "archiveCapture": false
}
```

Tool: `not24getme_tool_bookmark_create`

---

## 8. Error codes (in-app banner)

| Code                        | Meaning                      | Action                     |
| --------------------------- | ---------------------------- | -------------------------- |
| `mcp_init_failed`           | Relay handshake failed       | Start relay on 9333, retry |
| `mcp_extension_unavailable` | No `navigator.modelContext`  | Use Local Agent            |
| `mcp_script_load_failed`    | Page runtime failed to load  | Reload tab                 |
| `mcp_connect_failed`        | Generic connect failure      | §5 clean reset             |
| `mcp_feature_disabled`      | Flag off in environment      | Not available              |
| `mcp_viewport_unsupported`  | Screen too narrow            | Widen window               |
| `mcp_register_disallowed`   | Capability blocked by policy | Report to engineering      |

---

## 9. Verification checklist (done = working)

- [ ] Exactly one relay listens on `127.0.0.1:9333`
- [ ] `~/.webmcp/relay-port.json` port is `9333`
- [ ] One browser tab open on `app.not24get.me`, signed in
- [ ] WebMCP panel: **Connected via Local Agent**
- [ ] `webmcp_list_sources`: `count ≥ 1`
- [ ] `webmcp_list_tools`: 6 unsuffixed `not24getme_tool_*` tools
- [ ] `not24getme_tool_workspace_list` returns within 5s
- [ ] Folder/bookmark writes appear in the UI without manual refresh

---

## 10. When to escalate

Escalate to engineering if **all** of the following are true:

1. Clean reset (§5) completed twice.
2. Single tab, single relay, signed-in session confirmed.
3. `webmcp_list_sources` ≥ 1 but **every** tool still times out at 25s.
4. Browser Network tab shows API calls failing (401/5xx) during tool use.

Include: relay `lsof` output, `relay-port.json`, WebMCP diagnostics screenshot, MCP host
(Cursor) version, and browser used.