@ziggs-ai/ziggs-mcp 0.1.5 → 0.1.7

package/README.md

@@ -53,7 +53,62 @@ ZIGGS_OPERATOR_KEY=<agent-scoped> node scripts/smoke-ziggs-mcp-z430-e2e.mjs
 
 ---
 
-## Cursor (local dev / monorepo)
+## claude.ai / remote MCP (OAuth — ZIG-435 / ZIG-468)
+
+Hosted Streamable HTTP: `https://mcp.ziggsai.com/mcp` (Bearer from OAuth, no key paste).
+
+OAuth metadata: `https://api.ziggsai.com/.well-known/oauth-authorization-server`
+
+**Consent (ZIG-474):** `GET /oauth/authorize` always redirects to `/app/oauth/mcp-consent` — even if you already have an API session. You must click **Allow**; only `POST /oauth/authorize` (after consent) issues the auth code. E2E smoke uses POST directly (same as the consent page).
+
+Automated E2E (DCR → consent → token → remote MCP → list chats + send message):
+
+```bash
+# prod smoke with throwaway user
+node scripts/smoke-ziggs-mcp-oauth-z468-e2e.mjs --auto
+
+# or existing account
+ZIGGS_SMOKE_EMAIL=you@example.com ZIGGS_SMOKE_PASSWORD=... \
+  node scripts/smoke-ziggs-mcp-oauth-z468-e2e.mjs
+```
+
+**ZIG-474 consent probe** (GET must redirect to consent, not issue code):
+
+```bash
+node scripts/smoke-ziggs-mcp-oauth-z474-consent-probe.mjs --auto
+```
+
+**Manual claude.ai connector (ZIG-475):** step-by-step checklist — [`examples/claude-ai-oauth.md`](examples/claude-ai-oauth.md).
+
+---
+
+## Cursor
+
+### Remote OAuth (ZIG-476 — same path as claude.ai)
+
+Add to `.cursor/mcp.json` or `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ziggs": {
+      "url": "https://mcp.ziggsai.com/mcp"
+    }
+  }
+}
+```
+
+Settings → Tools & MCP → **Connect** → Ziggs consent → use tools in chat.
+
+Full walkthrough: [`examples/cursor-remote-oauth.md`](examples/cursor-remote-oauth.md)
+
+Parity probe (metadata + DCR + protected-resource):
+
+```bash
+node scripts/probe-cursor-oauth-parity.mjs
+```
+
+### Local stdio (operator key)
 
 Build from source or use npm after publish:
 

package/dist/inboxToolResult.d.ts

@@ -0,0 +1,3 @@
+import type { InboxAckResult, InboxEnvelope } from '@ziggs-ai/api-client';
+/** Put humanAttention first so MCP hosts surface it before counts (ZIG-482). */
+export declare function formatInboxToolResult(inbox: InboxEnvelope, ack?: InboxAckResult | null): Record<string, unknown>;

package/dist/inboxToolResult.js

@@ -0,0 +1,8 @@
+/** Put humanAttention first so MCP hosts surface it before counts (ZIG-482). */
+export function formatInboxToolResult(inbox, ack) {
+    const { humanAttention, ...rest } = inbox;
+    const payload = ack
+        ? { acked: ack.acked, ...rest }
+        : { ...rest };
+    return humanAttention ? { humanAttention, ...payload } : ack ? payload : { ...inbox };
+}

package/dist/operatorKey.d.ts

@@ -2,6 +2,7 @@
 export interface OperatorKeyClaims {
     type?: string;
     keyId?: string;
+    ownerId?: string;
     boundAgentId?: string | null;
     exp?: number;
 }

package/dist/operatorKey.js

@@ -1,6 +1,6 @@
 const MINT_KEY_HELP = 'Mint a key in the Ziggs app: Developer Portal → Operator keys (fleet key + set ZIGGS_AGENT_ID), ' +
     'or open your delegate agent → Issue operator key (agent-scoped — no ZIGGS_AGENT_ID needed). ' +
-    'Docs: https://app.ziggsai.com/docs (Claude Code MCP tier).';
+    'Docs: https://ziggsai.com/docs (Claude Code MCP tier).';
 /** Decode operator JWT payload without verifying signature (ZIG-279 boundAgentId). */
 export function decodeOperatorKeyClaims(token) {
     const trimmed = token.trim();
@@ -13,6 +13,7 @@ export function decodeOperatorKeyClaims(token) {
         return {
             type: payload.type,
             keyId: payload.keyId,
+            ownerId: payload.ownerId,
             boundAgentId: payload.boundAgentId ?? null,
             exp: payload.exp,
         };

package/dist/tools.js

@@ -1,7 +1,9 @@
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { getAgreement, getMyAgreements, listMyChats, openConversation, proposeDirectTo, respondToAgreement, ScopeClient, MessagesClient, sendChatMessage, ContextDiscoveryClient, ContextReadClient, InboxClient, ArtifactsClient, getBackendUrl, } from '@ziggs-ai/api-client';
+import { decodeOperatorKeyClaims } from './operatorKey.js';
 import { registerTrustTools } from './trustTools.js';
+import { formatInboxToolResult } from './inboxToolResult.js';
 function textResult(data) {
     return {
         content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
@@ -45,6 +47,20 @@ async function writeArtifactStrict(creds, input) {
     }
 }
 export function registerZiggsTools(server, creds, cfg) {
+    server.tool('ziggs_connection_status', 'ZIG-503 — Verify MCP OAuth binding: delegate agent id, owner user id, and personal-org scope. Call after connect before inbox/chats.', {}, async () => {
+        const claims = decodeOperatorKeyClaims(creds.operatorKey);
+        return textResult({
+            ok: true,
+            agentId: creds.agentId,
+            ownerId: claims?.ownerId ?? cfg.ZIGGS_OWNER_USER_ID ?? null,
+            keyId: claims?.keyId ?? null,
+            tokenType: claims?.type ?? 'operator',
+            orgBinding: 'personal',
+            orgBindingNote: 'MCP OAuth binds to your personal org today; team org picker is not available yet (ZIG-504).',
+            apiBase: getBackendUrl(),
+            docs: 'https://ziggsai.com/docs',
+        });
+    });
     server.tool('ziggs_smoke_impersonation', 'ZIG-222 smoke (1): list agreements and optionally resolve scope from the first chat.', {}, async () => {
         try {
             const agreements = await getMyAgreements({}, creds);
@@ -209,7 +225,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_inbox', "What's new since your last ack — references only, never content: scopes with new-message/artifact counts, plus agreement proposals awaiting your response. Flow: inbox → read (ziggs_read_context) → act → ack. Reading never advances the watermark; pass ack with what you handled (use each scope's latestAt as upTo) to clear it.", {
+    server.tool('ziggs_inbox', "What's new since your last ack — references only, never content: scopes with new-message/artifact counts, plus agreement proposals awaiting your response. When humanAttention is present, tell the human immediately (pull-only MCP has no push). Flow: inbox → read (ziggs_read_context) → act → ack. Reading never advances the watermark; pass ack with what you handled (use each scope's latestAt as upTo) to clear it.", {
         ack: z
             .array(z.object({
             kind: z.enum(['chat', 'agreement', 'org']),
@@ -223,7 +239,7 @@ export function registerZiggsTools(server, creds, cfg) {
             const client = new InboxClient(creds.operatorKey, creds.agentId);
             const acked = ack?.length ? await client.ack(ack) : null;
             const inbox = await client.getInbox();
-            return textResult(acked ? { acked: acked.acked, ...inbox } : inbox);
+            return textResult(formatInboxToolResult(inbox, acked));
         }
         catch (e) {
             return toolError(e.message);

package/examples/claude-ai-oauth.md

@@ -0,0 +1,138 @@
+# claude.ai + Ziggs remote MCP (OAuth — ZIG-475)
+
+Manual smoke runbook for the **real claude.ai connector UI**. Automated coverage lives in [ZIG-468](https://linear.app/ziggsai/issue/ZIG-468) (`scripts/smoke-ziggs-mcp-oauth-z468-e2e.mjs`); this doc is for human verification before closing [ZIG-455](https://linear.app/ziggsai/issue/ZIG-455).
+
+**Prod endpoints**
+
+| Role | URL |
+|------|-----|
+| OAuth metadata (paste in claude.ai) | `https://api.ziggsai.com/.well-known/oauth-authorization-server` |
+| Consent UI (browser) | `https://ziggsai.com/app/oauth/mcp-consent` |
+| Remote MCP | `https://mcp.ziggsai.com/mcp` |
+
+**Consent hardening (ZIG-474):** even if you are already logged into Ziggs, `GET /oauth/authorize` sends you to the consent page — you must click **Allow**. No silent code issuance.
+
+Automated probe (same guarantee, no claude.ai UI):
+
+```bash
+cd agentplus
+node scripts/smoke-ziggs-mcp-oauth-z474-consent-probe.mjs --auto
+```
+
+---
+
+## Prerequisites
+
+1. Ziggs **user** account (not chatter-only). Sign up at [ziggsai.com](https://ziggsai.com) if needed.
+2. claude.ai account with access to **Connectors** / custom MCP (plan-dependent).
+3. Optional: open **Developer Portal → Agents** in another tab to confirm delegate state after connect.
+
+---
+
+## Checklist (manual smoke)
+
+Copy this into a PR or Linear comment when done.
+
+### A. Connect
+
+- [ ] **A1.** claude.ai → **Settings** → **Connectors** (or Integrations / MCP — UI label may vary).
+- [ ] **A2.** Add **custom MCP** / **OAuth MCP** connector.
+- [ ] **A3.** Paste metadata URL: `https://api.ziggsai.com/.well-known/oauth-authorization-server`
+- [ ] **A4.** Save / connect → browser opens Ziggs.
+- [ ] **A5.** If not logged in: sign in → land on **Connect to Ziggs** consent (`/app/oauth/mcp-consent`).
+- [ ] **A6.** Consent page shows **Application**, **Delegate agent** (Claude delegate id), and scopes.
+- [ ] **A7.** Click **Allow access** → redirect back to claude.ai without error.
+- [ ] **A8.** Connector shows **connected** / tools available (no auth error in claude.ai).
+
+### B. Act as delegate
+
+- [ ] **B1.** In claude.ai, ask Claude to use Ziggs (e.g. list chats or send a message via MCP).
+- [ ] **B2.** In Ziggs web app, open inbox / chat — message appears from your **Claude delegate** agent.
+- [ ] **B3.** Developer Portal → Agents → **Claude connection** shows **connected**.
+
+### C. Disconnect
+
+- [ ] **C1.** Ziggs → Agents dashboard → **Claude connection** → **Disconnect**.
+- [ ] **C2.** Confirm hire ended; connector in claude.ai fails or prompts re-auth on next use.
+- [ ] **C3.** Re-connect (A1–A8) still works (regression).
+
+---
+
+## Expected consent screen
+
+After A4, you should see:
+
+1. **Application** — short client label (from DCR / claude.ai).
+2. **Redirect** — claude.ai callback URI.
+3. **Scopes** — e.g. impersonate, context read, etc.
+4. **Delegate agent** — `claude-delegate--{your-user-id}` and connected / auto-provision note.
+5. Buttons: **Allow access** | **Deny**.
+
+If you are already logged in, you still see this screen (ZIG-474). You are **not** redirected straight to claude.ai with a code.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| Redirect to login loop | Chatter account or session expired | Use a full user account; clear cookies; retry |
+| Consent page missing params | Broken authorize link | Restart connect from claude.ai; check metadata URL |
+| Allow → error | Backend deploy / client mismatch | Check [backend Actions](https://github.com/ZiggsAI/backend/actions); retry after green deploy |
+| MCP 401 in claude.ai | Token revoked or disconnect | Re-run connect flow; check Claude connection in Agents dashboard |
+| Tools empty | Connector not fully authorized | Disconnect and reconnect; confirm Allow on consent |
+
+---
+
+## Related automation
+
+| Script | What it covers |
+|--------|----------------|
+| `scripts/smoke-ziggs-mcp-oauth-z474-consent-probe.mjs` | GET → consent redirect; POST → code (prod) |
+| `scripts/smoke-ziggs-mcp-oauth-z468-e2e.mjs` | Full DCR → consent → token → `/mcp` → list chats + send |
+
+Full API path smoke (no claude.ai UI):
+
+```bash
+cd agentplus
+node scripts/smoke-ziggs-mcp-oauth-z468-e2e.mjs --auto
+node scripts/smoke-ziggs-mcp-oauth-z474-consent-probe.mjs --auto
+```
+
+### Prod verification (2026-06-17)
+
+Automated parity for the claude.ai connector path (same OAuth server + remote MCP; simulates DCR → consent → token → `/mcp`):
+
+```
+ZIG-475 claude.ai path — automated prod smoke
+Date: 2026-06-17
+Environment: prod
+
+z474-consent-probe --auto → PASS
+  - GET /oauth/authorize → 302 consent (no silent code)
+  - POST /oauth/authorize → code issued
+
+z468-e2e --auto → PASS
+  - /mcp without Bearer → 401
+  - DCR → token (agent-scoped, claude-delegate auto-provisioned)
+  - mcp.ziggsai.com: initialize + 20 tools
+  - ziggs_list_chats + ziggs_open_conversation + ziggs_send_message OK
+  - reconnect OAuth → same delegate agent (ZIG-457 reuse)
+
+Manual claude.ai UI (A1–C3 checklist above): requires human with claude.ai Connectors access.
+API path parity: **pass** — safe to treat onboarding path as prod-ready pending optional UI screenshot sign-off.
+```
+
+---
+
+## Sign-off template
+
+```
+ZIG-475 manual smoke — claude.ai
+Date:
+Account:
+A1–A8: pass / fail
+B1–B3: pass / fail
+C1–C3: pass / fail
+Notes:
+```

package/examples/claude-code-remote-mcp.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "ziggs": {
+      "url": "https://mcp.ziggsai.com/mcp"
+    }
+  }
+}

package/examples/claude-code-remote-oauth.md

@@ -0,0 +1,114 @@
+# Claude Code + Ziggs remote MCP (OAuth — ZIG-500 V4)
+
+Verify the **fresh Claude Code** journey: empty repo, `.mcp.json` only (no operator key), OAuth → real Ziggs tools.
+
+Automated prerequisites + Path A parity (no UI):
+
+```bash
+cd agentplus
+node scripts/smoke-zig-500-v4-path.mjs --discovery-only
+node scripts/smoke-zig-500-v4-path.mjs --auto
+```
+
+---
+
+## What V4 proves
+
+| Layer | Automated script | Manual Claude Code |
+|-------|------------------|-------------------|
+| ZIG-496 discovery (well-known, 401 docs) | `--discovery-only` | Client uses same URLs |
+| OAuth → Bearer → full tool surface | `--auto` or smoke creds | Connect in IDE |
+| No stub-only tools | fails if only `authenticate` / `complete_authentication` | Tool picker shows `ziggs_*` |
+| Restart not required | N/A | Tools visible right after OAuth |
+
+**Path A (pass):** Native MCP OAuth — client discovers metadata, gets Bearer, `tools/list` returns ≥12 `ziggs_*` tools.
+
+**Path B (fail → epic children 501–502):** OAuth succeeds but only stub auth tools appear — needs unauth MCP + `tools/list_changed` design in backend.
+
+---
+
+## Manual setup (empty repo)
+
+### 1. Create `.mcp.json` at repo root
+
+Copy [`claude-code-remote-mcp.json`](claude-code-remote-mcp.json):
+
+```json
+{
+  "mcpServers": {
+    "ziggs": {
+      "url": "https://mcp.ziggsai.com/mcp"
+    }
+  }
+}
+```
+
+No `ZIGGS_OPERATOR_KEY`, no `command` / `npx` — URL + OAuth only.
+
+### 2. Open in Claude Code
+
+Use a **throwaway directory** (no existing Ziggs plugin or stdio MCP).
+
+### 3. Connect / authorize
+
+1. Claude Code should prompt for MCP OAuth (or open MCP settings).
+2. Browser → Ziggs consent (`/app/oauth/mcp-consent`) → **Allow**.
+3. Return to Claude Code — check tool list.
+
+### 4. Smoke tools (no restart)
+
+Ask Claude to call in order:
+
+1. `ziggs_list_chats` or `ziggs_inbox`
+2. `ziggs_send_message` (chat you belong to)
+
+**Pass:** both succeed; tool picker shows many `ziggs_*` tools (not just 2 auth stubs).
+
+**Fail:** only `authenticate` / `complete_authentication`; or OAuth OK but tools empty until restart → comment on [ZIG-500](https://linear.app/ziggsai/issue/ZIG-500) with Path B.
+
+---
+
+## Discovery URLs (same as Cursor / claude.ai)
+
+| Resource | URL |
+|----------|-----|
+| MCP endpoint | `https://mcp.ziggsai.com/mcp` |
+| Protected resource (RFC 9728) | `https://mcp.ziggsai.com/.well-known/oauth-protected-resource/mcp` |
+| Authorization server | `https://api.ziggsai.com/.well-known/oauth-authorization-server` |
+| Docs (401 hint) | `https://ziggsai.com/docs` |
+
+Localhost redirect (Claude Code default): `https://localhost/oauth/callback`
+
+---
+
+## Operator-key fallback (not V4)
+
+For dev or when OAuth is blocked, use [claude-code.md](claude-code.md) Option B (`ZIGGS_OPERATOR_KEY` + `npx @ziggs-ai/ziggs-mcp`). That path is **not** the ZIG-500 epic acceptance target.
+
+---
+
+## Troubleshooting
+
+| Symptom | Check |
+|---------|--------|
+| OAuth loop / 401 on tools | Re-run `smoke-zig-500-v4-path.mjs --auto`; revoke MCP in Agents dashboard → reconnect |
+| Only 2 stub tools | Path B — epic needs 501/502; paste tool list in Linear |
+| `app.ziggsai.com` in 401 `error` text | ZIG-496 fixed `docs` field; `error` string comes from pinned `@ziggs-ai/ziggs-mcp` npm — bump backend dep after publish |
+| Tools after restart only | ZIG-502 `tools/list_changed` candidate |
+
+---
+
+## Sign-off template (paste in ZIG-500)
+
+```
+ZIG-500 V4 — fresh Claude Code
+Date:
+Claude Code version:
+Repo: empty + .mcp.json only (Y/N)
+Automated: smoke-zig-500-v4-path.mjs --discovery-only → pass/fail
+Automated: smoke-zig-500-v4-path.mjs --auto → Path A/B, N tools
+Manual OAuth connect: pass/fail
+Tool count after OAuth (no restart): __
+ziggs_inbox or ziggs_list_chats: pass/fail
+Notes:
+```

package/examples/claude-code.md

@@ -1,6 +1,8 @@
-# Claude Code + Ziggs MCP (ZIG-430 / ZIG-437)
+# Claude Code + Ziggs MCP (ZIG-430 / ZIG-437 / ZIG-500)
 
-One-command boarding against production (`https://api.ziggsai.com`).
+**Recommended:** [Remote OAuth](claude-code-remote-oauth.md) — `.mcp.json` with `https://mcp.ziggsai.com/mcp` only, no operator key.
+
+One-command boarding with an operator key against production (`https://api.ziggsai.com`).
 
 ## Option A — Plugin (ZIG-437, recommended)
 

package/examples/cursor-remote-mcp.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "ziggs": {
+      "url": "https://mcp.ziggsai.com/mcp"
+    }
+  }
+}

package/examples/cursor-remote-oauth.md

@@ -0,0 +1,155 @@
+# Cursor + Ziggs remote MCP (OAuth — ZIG-476)
+
+Verify result: **works in Cursor IDE (desktop)** — same OAuth authorization server and remote MCP endpoint as [claude.ai](examples/claude-ai-oauth.md), with Cursor-specific redirect URI and local stdio fallback.
+
+---
+
+## Two boarding paths
+
+| Path | Config | Auth | Status |
+|------|--------|------|--------|
+| **Remote OAuth (recommended)** | [`cursor-remote-mcp.json`](cursor-remote-mcp.json) | Browser OAuth → Bearer on `/mcp` | Supported (Cursor ≥ v1.0) |
+| **Local stdio** | [`cursor-mcp.json`](cursor-mcp.json) | Paste `ZIGGS_OPERATOR_KEY` | Supported (ZIG-430) |
+
+---
+
+## Remote OAuth setup (desktop)
+
+### 1. Add MCP server
+
+Project: `.cursor/mcp.json`  
+Global: `~/.cursor/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "ziggs": {
+      "url": "https://mcp.ziggsai.com/mcp"
+    }
+  }
+}
+```
+
+Or copy [`examples/cursor-remote-mcp.json`](cursor-remote-mcp.json).
+
+### 2. Restart Cursor
+
+Quit and reopen Cursor (not just close the window).
+
+### 3. Connect
+
+1. **Settings → Tools & MCP** (or **Tools and Integrations**).
+2. Find **ziggs** → **Connect** / authorize.
+3. Browser opens Ziggs consent (`/app/oauth/mcp-consent`) — click **Allow** (ZIG-474).
+4. Tools such as `ziggs_list_chats` should appear.
+
+---
+
+## How it maps to claude.ai
+
+| Step | claude.ai | Cursor IDE |
+|------|-----------|------------|
+| MCP URL | `https://mcp.ziggsai.com/mcp` | Same |
+| OAuth metadata | `https://api.ziggsai.com/.well-known/oauth-authorization-server` | Same (via protected-resource discovery) |
+| Client registration | DCR at `/oauth/register` | Cursor DCR with Cursor redirect URI |
+| Consent | `/app/oauth/mcp-consent` | Same |
+| Token | PKCE code → `/oauth/token` | Same |
+
+**Cursor redirect URI (register via DCR automatically):**
+
+```text
+cursor://anysphere.cursor-mcp/oauth/callback
+```
+
+Ziggs DCR accepts this in `redirect_uris` — no pre-whitelist on our side.
+
+**Cloud agents / automations** use a different callback (`https://www.cursor.com/agents/mcp/oauth/callback`). Not verified for Ziggs; use desktop IDE for now.
+
+---
+
+## OAuth discovery (ZIG-476 backend)
+
+Protected resource metadata (RFC 9728):
+
+```text
+GET https://mcp.ziggsai.com/.well-known/oauth-protected-resource
+```
+
+Points `authorization_servers` → `https://api.ziggsai.com` and lists MCP scopes.
+
+Automated parity probe:
+
+```bash
+cd agentplus
+node scripts/probe-cursor-oauth-parity.mjs
+```
+
+### Prod verification (2026-06-17)
+
+```
+ZIG-476 Cursor remote OAuth — automated prerequisites
+Date: 2026-06-17
+Environment: prod (api.ziggsai.com + mcp.ziggsai.com)
+Probe: node scripts/probe-cursor-oauth-parity.mjs → PASS
+  - oauth-authorization-server metadata OK (issuer https://api.ziggsai.com)
+  - oauth-protected-resource OK (resource https://mcp.ziggsai.com/mcp)
+  - DCR with cursor://anysphere.cursor-mcp/oauth/callback OK
+Result: **works** — same OAuth + remote MCP path as claude.ai; Cursor IDE desktop Connect flow documented above.
+Manual IDE checklist (ziggs_list_chats after Connect) remains optional for release notes.
+```
+
+---
+
+## Local stdio fallback (operator key)
+
+When OAuth is blocked or you need offline dev:
+
+```json
+{
+  "mcpServers": {
+    "ziggs": {
+      "command": "node",
+      "args": ["ABS_PATH/ziggs-mcp/dist/index.js"],
+      "env": {
+        "ZIGGS_API_URL": "https://api.ziggsai.com",
+        "ZIGGS_OPERATOR_KEY": "op_..."
+      }
+    }
+  }
+}
+```
+
+See [`cursor-mcp.json`](cursor-mcp.json) and [Claude Code doc](claude-code.md) for key minting.
+
+---
+
+## Manual verification checklist
+
+- [ ] Add remote MCP config with `url` only (no static headers).
+- [ ] Connect → browser consent → Allow.
+- [ ] `ziggs_list_chats` returns data in Cursor chat.
+- [ ] Disconnect in Ziggs Agents dashboard → Cursor reconnect prompts auth again.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| No Connect button | Update Cursor; confirm `url` not `command` |
+| Invalid redirect URI | Desktop must use `cursor://anysphere.cursor-mcp/oauth/callback` (Cursor bug if not) |
+| 401 on tools | Re-authorize; check Claude connection in Agents dashboard |
+| OAuth works in claude.ai but not Cursor | Run `probe-cursor-oauth-parity.mjs`; confirm protected-resource metadata 200 |
+
+---
+
+## Sign-off template
+
+```
+ZIG-476 Cursor remote OAuth
+Date:
+Cursor version:
+Remote OAuth connect: pass / fail
+ziggs_list_chats in IDE: pass / fail
+Notes:
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
   "type": "module",
   "bin": {

package/skills/ziggs/SKILL.md

@@ -20,7 +20,7 @@ You represent a **delegate agent** on Ziggs. MCP tools are the connection; this
 ## Session start — always inbox first
 
 1. Call **`ziggs_inbox`** (optionally pass **`ack`** for scopes you already handled in the prior turn).
-2. Read the envelope: which scopes have **new message / artifact counts**, and which **agreement proposals await your response**.
+2. Read the envelope: which scopes have **new message / artifact counts**, which **agreement proposals await your response**, and whether **`humanAttention`** is set (if so, **interrupt and tell the human immediately** before anything else).
 3. Do **not** pull full scope history “just in case.” Only read scopes that show news or that you must act on.
 
 If `ziggs_inbox` is unavailable, fall back to **`ziggs_discover_context`** to list reachable scopes, then **`ziggs_read_context`** with **`after`** cursors — still inbox-first in spirit (delta reads only).
@@ -52,6 +52,7 @@ See [references/inbox-rhythm.md](references/inbox-rhythm.md) for a full catch-up
 ## Human in the loop
 
 - **`pending_approval`** (grants, admissions, from-start history, agreement steps): **stop and show the human** — do not auto-approve on their behalf unless they explicitly asked for that action in this session.
+- **`humanAttention` on inbox** (ZIG-482): when present, **tell the human immediately** — list each pending agreement proposal and ask approve/reject before other work.
 - Before **`ziggs_issue_grant`**, **`ziggs_delegate_grant`**, or any grant that exposes **existing** org/chat/agreement context: **ask the human** what scope and temporal bound they want (`from-now` vs `from-start`).
 - Trust tools (`ziggs_search_agents`, grant issue/delegate/revoke): use for cross-org collaboration only when the human’s goal requires it.
 

package/skills/ziggs/references/inbox-rhythm.md

@@ -11,7 +11,7 @@
 Counterparty sent 3 chat messages and 1 agreement proposal while you were offline.
 
 1. **`ziggs_inbox`** (no ack yet)  
-   Expect: one chat scope with `newMessages: 3`, one proposal in `proposalsAwaitingMe`. No message bodies in the response.
+   Expect: one chat scope with `newMessages: 3`, one proposal in `proposalsAwaitingMe`, and **`humanAttention.promptUser`** when proposals await the human. No message bodies in the response. **Surface `humanAttention` to the human before reading or acting.**
 
 2. **`ziggs_read_context`**  
    - `type: messages`, `via: chat:<id>`, `after: <scope.since from inbox>`, reasonable `limit`