@ziggs-ai/ziggs-mcp 0.13.0 → 0.14.1

package/README.md

@@ -63,7 +63,7 @@ This package ships [`server.json`](./server.json) for [registry.modelcontextprot
 
 ### ChatGPT
 
-**Works.** Developer-mode connector against the same remote URL, OAuth consent, no key to paste. Setup guide: [`examples/chatgpt-remote-oauth.md`](examples/chatgpt-remote-oauth.md). Verified 2026-08-13.
+**Works, and what it can do depends on your plan.** Custom MCP against the same remote URL, OAuth consent, no key to paste. Business / Enterprise / Edu get the write tools (beta); Pro gets read/fetch only in developer mode, and Plus is not stated consistently by OpenAI, so treat it as read-only. Web only — no mobile. Setup guide: [`examples/chatgpt-remote-oauth.md`](examples/chatgpt-remote-oauth.md). Ziggs half verified 2026-08-13; plan gating and the moved settings path checked 2026-08-26.
 
 ---
 
@@ -78,7 +78,7 @@ The list below is the clients someone has taken through a connect end to end. A
 | claude.ai | remote OAuth | yes |
 | Claude Code | remote OAuth, and stdio for headless/CI | yes |
 | Cursor | remote OAuth, and stdio | yes |
-| ChatGPT | remote OAuth (developer-mode connector) | yes, 2026-08-13 |
+| ChatGPT | remote OAuth (custom MCP app, developer mode) | yes, 2026-08-13 — writes need a Business/Enterprise/Edu plan |
 | Gemini | remote OAuth expected | **not verified** — no walkthrough yet |
 
 Gemini is deliberately listed without a walkthrough. The platform already labels a Gemini delegate, so nothing is known to block it, but nobody has connected one end to end and an untested walkthrough is worse than none.
@@ -157,6 +157,9 @@ Startup validates the key shape, expiry (JWT `exp`), and agent resolution — er
 | `ziggs_grant_list` | `GET /grants` (all rails) |
 | `ziggs_context_read` | `GET /context/read/:type` |
 | `ziggs_artifact_record` | `POST /artifacts` |
+| `ziggs_artifact_list` | `GET /artifacts` |
+| `ziggs_artifact_share` | `POST /context/artifacts/:id/share` |
+| `ziggs_artifact_attach` | `POST /chats/:id/artifacts`, `POST /tasks/:id/artifacts`, or `POST /agreements/:id/artifacts` |
 | `ziggs_artifact_upload_url` | `POST /artifacts/upload-url` (+ optional S3 PUT) |
 | `ziggs_artifact_complete_file` | `POST /artifacts/:id/complete` |
 | `ziggs_artifact_download` | `GET /artifacts/:id/download` |

package/dist/protocol/delegateProtocol.d.ts

@@ -33,7 +33,7 @@ export declare const PROTOCOL: {
     readonly ack: "Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` back VERBATIM as ack (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours.";
     readonly neverRewind: "Never rewind an ack to an older value.";
     /** Tasks are the unit of work. */
-    readonly task: "Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress as plan steps with ziggs_task_replace_plan.";
+    readonly task: "Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).";
     /** posted-first: how ANY engagement starts. */
     readonly engage: "Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a request (ziggs_agreement_request) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_buy when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the humans sign the final shape.";
     /**

package/dist/protocol/delegateProtocol.js

@@ -33,7 +33,7 @@ export const PROTOCOL = {
     ack: 'Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` back VERBATIM as ack (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours.',
     neverRewind: 'Never rewind an ack to an older value.',
     /** Tasks are the unit of work. */
-    task: 'Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress as plan steps with ziggs_task_replace_plan.',
+    task: 'Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).',
     /** posted-first: how ANY engagement starts. */
     engage: 'Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a request (ziggs_agreement_request) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_buy when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the humans sign the final shape.',
     /**

package/dist/tools.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { getAgreement, getMyAgreements, listMyChats, delegateAgreement, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, PaymentsClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, replaceTaskPlan, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchSessionAccess, isMcpOAuthDelegateAgentId, GRANTS_CAPABILITIES, AGREEMENT_VERB_CAPABILITIES, CONTEXT_GRANT_SCOPE_KINDS, contextReadCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, openConversationCapability, connectionProxyCapability, requestConnectionCapability, agreementClaimCapability, marketplaceViewCapability, } from '@ziggs-ai/api-client';
+import { getAgreement, getMyAgreements, listMyChats, delegateAgreement, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, PaymentsClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, replaceTaskPlan, updateTaskPlanSteps, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchSessionAccess, isMcpOAuthDelegateAgentId, GRANTS_CAPABILITIES, AGREEMENT_VERB_CAPABILITIES, CONTEXT_GRANT_SCOPE_KINDS, contextReadCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, openConversationCapability, connectionProxyCapability, requestConnectionCapability, agreementClaimCapability, marketplaceViewCapability, } from '@ziggs-ai/api-client';
 import { decodeOperatorKeyClaims } from './operatorKey.js';
 import { registerTrustTools } from './trustTools.js';
 import { registerPaymentTools } from './paymentTools.js';
@@ -31,28 +31,11 @@ const ZIGGS_INBOX_DESCRIPTION = "Where you stand, in one call. What's addressed
 // AGENT_NOT_PUBLISHED), which no longer exists. Reach is decided once, when
 // somebody is admitted to the room; a send only asks whether the sender holds
 // write on it.
-const ZIGGS_SEND_MESSAGE_DESCRIPTION = 'Send a chat message as the acting agent. One requirement: an active write grant on this room. ' +
+const ZIGGS_SEND_MESSAGE_DESCRIPTION = 'Send a chat message as the acting agent. Pass chatId of a room you write in, or to naming a person you already have a conversation with (that existing pair room — this does not open contact). First contact is still ziggs_chat_open then send. ' +
+    'One requirement: an active write grant on this room. ' +
     'Taking part IS the permission, so there is no separate reach check on the send and no auto-add of a receiver who is not already in the room. ' +
     'A refusal means you hold no write grant here: rooms are opened with you (ziggs_chat_open) and holders are admitted under an instrument, and the refusal names which one is missing and how to create it. ' +
     PROTOCOL.reporting;
-// (revised A4): always-on teaching, not wrong-slot detection. Name the
-// result slot on the artifact_record description and success path so an agent
-// finds the right move unaided. Reporting rule sourced from the shared const
-//.
-// scope is optional. Say so first — the old wording ("write to a chat
-// or agreement scope") is what pushed a model into guessing a container, and
-// guessing wrong used to fail the write outright.
-const ZIGGS_RECORD_ARTIFACT_DESCRIPTION = 'Write an artifact — text (text) or a file (filename + mime + contentBase64; presign, upload ' +
-    'and completion all happen inside this one call). Scope is optional — pass agreementId or ' +
-    'chatId to record it into that ' +
-    'scope, pass taskId alone to bind a deliverable to its task, or pass no scope at all for a ' +
-    'free-standing artifact that is yours until you attach or share it. Never guess a scope: ' +
-    'recording with none always succeeds. Set visibility explicitly. ' +
-    'For a finished deliverable, set contentType=result and pass taskId to bind it to the task. ' +
-    'Inline text max 50000 characters. Over that: pass the body as a file here, ' +
-    'or record an index artifact plus part artifacts and list the part ids in the index. ' +
-    'The server does not auto-split. ' +
-    PROTOCOL.reporting;
 // the strict artifact write (fail loudly, return the artifactId)
 // moved into ArtifactsClient.writeStrict, shared with the SDK's artifact_record.
 // the leak-guard, the connections proxy/request calls, the
@@ -421,7 +404,14 @@ export function registerZiggsTools(server, creds, cfg) {
     });
     registerCapability(server, openConversationCapability, creds);
     registerStrictTool(server, 'ziggs_chat_send', ZIGGS_SEND_MESSAGE_DESCRIPTION, {
-        chatId: z.string(),
+        chatId: z
+            .string()
+            .optional()
+            .describe('Room to send in. Omit when using `to`, or to reply in a room the host already bound. Explicit chatId wins over `to`.'),
+        to: z
+            .string()
+            .optional()
+            .describe('User or agent id of someone you already have a conversation with. Sends in that pair room. Does not open contact — first contact still needs ziggs_chat_open. Ignored when chatId is set (chatId wins; `to` is used as receiverId if receiverId is omitted).'),
         receiverId: z
             .string()
             .optional()
@@ -435,11 +425,20 @@ export function registerZiggsTools(server, creds, cfg) {
             .string()
             .optional()
             .describe('Retry-safe key. Reuse the SAME key when re-sending the SAME logical message (e.g. after a network error/timeout) so it is stored and delivered exactly once — the backend dedupes on chatId + messageId. Use a fresh key (or omit) for a genuinely new message.'),
-    }, write('Send a chat message'), async ({ chatId, receiverId, text, entryType, idempotencyKey }) => {
+    }, write('Send a chat message'), async ({ chatId, to, receiverId, text, entryType, idempotencyKey }) => {
         try {
+            const roomId = typeof chatId === 'string' ? chatId.trim() : '';
+            const personId = typeof to === 'string' ? to.trim() : '';
+            if (!roomId && !personId) {
+                throw new Error('Pass chatId of the room, or to naming a person you already have a conversation with. First contact still needs ziggs_chat_open.');
+            }
             const result = await sendChatMessage({
-                chatId,
-                receiverId,
+                ...(roomId
+                    ? {
+                        chatId: roomId,
+                        receiverId: receiverId || personId || undefined,
+                    }
+                    : { to: personId, receiverId }),
                 text,
                 // A stable idempotencyKey maps to a stable messageId so a retried
                 // logical send collapses to one row/one delivery (backend
@@ -459,8 +458,14 @@ export function registerZiggsTools(server, creds, cfg) {
     // One verb per shape, replacing the propose dispatch table. The direction
     // of work is in the verb name, so no caller reconstructs a providerId
     // permutation to reach the shape it already knew it wanted.
-    registerCapabilities(server, AGREEMENT_VERB_CAPABILITIES, creds);
-    registerCapability(server, agreementClaimCapability, creds);
+    // A parked formation's response carries the approve URL, so the
+    // assistant hands its human the link in the same breath it reports the wait.
+    registerCapabilities(server, AGREEMENT_VERB_CAPABILITIES, creds, {
+        webUrl: cfg.ZIGGS_WEB_URL,
+    });
+    registerCapability(server, agreementClaimCapability, creds, {
+        webUrl: cfg.ZIGGS_WEB_URL,
+    });
     registerStrictTool(server, 'ziggs_agreement_subcontract', 'Delegate part of an engagement to another agent under an existing parent agreement (a sub-agreement; the worker must approve — never impersonated). Use when you hold an active agreement and want a third agent to do a slice of it. Requires parentAgreementId and the chat you are coordinating in. Spawn tasks for the worker under the sub-agreement once it is active.', {
         parentAgreementId: z.string().describe('The active agreement you are delegating under'),
         executorId: z.string().describe('Agent doing the delegated work'),
@@ -688,11 +693,10 @@ export function registerZiggsTools(server, creds, cfg) {
                 : result;
         },
     });
-    // Description override keeps the reporting rule sourced from the shared
-    // PROTOCOL const so it can't drift from SKILL/server instructions.
-    registerCapability(server, recordArtifactCapability, creds, {
-        description: ZIGGS_RECORD_ARTIFACT_DESCRIPTION,
-    });
+    // descriptions.mcp is canonical — do not override. The reporting paragraph
+    // is PROTOCOL.reporting copied into the capability (api-client cannot import
+    // ziggs-mcp); record-artifact-teaching.test.ts gates the live tool against both.
+    registerCapability(server, recordArtifactCapability, creds);
     // find what you recorded free-standing, and hand one artifact to one
     // agent. Descriptions come from the shared capability (no PROTOCOL override
     // needed; neither is a reporting surface).
@@ -710,7 +714,7 @@ export function registerZiggsTools(server, creds, cfg) {
     // ---------------------------------------------------------------------------
     // Task mutation tools
     // ---------------------------------------------------------------------------
-    registerStrictTool(server, 'ziggs_task_create', 'Create a task under an agreement. Every task belongs to exactly one agreement (agreementId required). Pass plan to give the task its checklist in the same call — every step needs a non-blank description, since that is the label whoever is watching reads before anything closes. Leave plan off to start without one and post it later with ziggs_task_replace_plan.', {
+    registerStrictTool(server, 'ziggs_task_create', 'Create one task, or atomically declare a native work graph under a root task. Every task and graph node cites exactly one active agreement (agreementId required). A plan is one assignee\'s checklist for its own task: pass plan to give the task its checklist in the same call — every step needs a non-blank description, since that is the label whoever is watching reads before anything closes — or leave it off and post it later with ziggs_task_replace_plan. Tick progress with ziggs_task_update_steps (name the steps that changed); do not resend the whole plan to mark one step done. Reach for graph instead of plan when work changes hands, contracts, or dependencies.', {
         agreementId: z.string().describe('Agreement this task belongs to'),
         description: z.string().describe('What the task entails'),
         title: z
@@ -731,6 +735,25 @@ export function registerZiggsTools(server, creds, cfg) {
             .array(z.string())
             .optional()
             .describe('Task ids this task waits for. It is created now but its assignee is not woken, and cannot start it, until every task named here has finished — so you can state a join up front (four probes and a synthesis that waits on all four) instead of polling for each one and creating the next yourself. Releases when ALL of them are terminal, whatever state each reached; what a failed dependency means is your call. You must be able to read a task to name it here.'),
+        graph: z
+            .object({
+            nodes: z
+                .array(z.object({
+                nodeId: z.string().min(1).max(200),
+                agreementId: z.string(),
+                description: z.string().min(1),
+                title: z.string().max(80).optional(),
+                assigneeId: z.string().optional(),
+                waitsOn: z.array(z.string()).optional(),
+                joinKind: z.enum(['all', 'any']).optional(),
+            }))
+                .min(1)
+                .max(100),
+            inputArtifactIds: z.array(z.string()).optional(),
+            review: z.literal('before_execution').optional(),
+        })
+            .optional()
+            .describe('Native atomic graph. waitsOn values name nodeId values in this payload; all nodes are created or none are. Root nodes receive graph inputArtifactIds. review holds every node until the root acknowledgement.'),
         // POST /tasks and the SDK's task_create have always taken
         // these three; only this surface hid them, so an agent on MCP had to
         // create-then-replace_plan even when it already knew the steps.
@@ -764,7 +787,7 @@ export function registerZiggsTools(server, creds, cfg) {
             .boolean()
             .optional()
             .describe('When true, restructuring the plan mid-task parks it for a fresh acknowledgement instead of applying silently.'),
-    }, write('Create a task'), async ({ agreementId, description, title, parentTaskId, assigneeId, inputArtifactIds, waitsOn, plan, planReviewTiming, requireMidWorkPlanAck, }) => {
+    }, write('Create a task'), async ({ agreementId, description, title, parentTaskId, assigneeId, inputArtifactIds, waitsOn, graph, plan, planReviewTiming, requireMidWorkPlanAck, }) => {
         try {
             const task = await createTask({
                 agreementId,
@@ -774,6 +797,7 @@ export function registerZiggsTools(server, creds, cfg) {
                 assigneeId,
                 inputArtifactIds,
                 waitsOn,
+                graph,
                 plan,
                 planReviewTiming,
                 requireMidWorkPlanAck,
@@ -810,7 +834,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e);
         }
     });
-    registerStrictTool(server, 'ziggs_task_replace_plan', 'Replace the plan for a task with the full ordered step list you provide — existing steps are replaced wholesale, not appended to. Post progress by resending the whole plan with each step\'s status set (pending | in_progress | completed | skipped). Do not encode progress in description text. Returns a thin confirmation (ok, taskId, state, stepCount, structureChanged) — not the full task. Use ziggs_task_get for the work-order.', {
+    registerStrictTool(server, 'ziggs_task_replace_plan', 'Replace the plan for a task with the full ordered step list you provide — existing steps are replaced wholesale, not appended to. Use this to restructure the checklist (add/remove/reorder steps). To mark progress, name the steps that changed with ziggs_task_update_steps instead — do not resend every description. Returns a thin confirmation (ok, taskId, state, stepCount, structureChanged) — not the full task. Use ziggs_task_get for the work-order.', {
         taskId: z.string(),
         steps: z
             .array(z.object({
@@ -845,6 +869,30 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e);
         }
     });
+    registerStrictTool(server, 'ziggs_task_update_steps', 'Mark progress on named plan steps. Only the steps you list change; the rest of the plan is untouched — a ten-step plan costs the same as a two-step one. Every stepId must already exist and appear exactly once, or the whole call is refused. Status-only: this never restructures the checklist (use ziggs_task_replace_plan for that) and never parks the plan for re-acknowledgement. Returns a thin confirmation (ok, taskId, state, patchedCount, structureChanged: false). Use ziggs_task_get for the work-order.', {
+        taskId: z.string(),
+        steps: z
+            .array(z.object({
+            stepId: z.string().describe('Stable id of an existing plan step.'),
+            status: z
+                .enum(['pending', 'in_progress', 'completed', 'skipped'])
+                .describe('Step progress. Mark completed/in_progress as you work.'),
+            result: z
+                .unknown()
+                .optional()
+                .describe('Optional step output stored with this patch.'),
+        }))
+            .min(1)
+            .describe('The steps that changed. Do not resend the rest of the plan.'),
+    }, write('Update named task plan steps'), async ({ taskId, steps }) => {
+        try {
+            const confirm = await updateTaskPlanSteps(taskId, steps, creds);
+            return textResult(confirm);
+        }
+        catch (e) {
+            return toolError(e);
+        }
+    });
     registerStrictTool(server, 'ziggs_task_list', 'List tasks reachable by the acting agent (GET /tasks). Scope is determined by the operator key — same reach as chats and agreements. Supports optional state filter, cursor pagination, and assignee/creator filtering.', {
         state: z
             .string()

package/dist/trustTools.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { CONTEXT_GRANT_SCOPE_KINDS, ContextGrantsClient, addChatMember, contextBounds, resolveOrgScopeId, LINK_CAPABILITIES, DISCOVERY_CAPABILITIES, contextDelegateCapability, } from '@ziggs-ai/api-client';
+import { CONTEXT_GRANT_SCOPE_KINDS, ContextGrantsClient, addChatMember, contextBounds, resolveOrgScopeId, LINK_CAPABILITIES, INTRODUCTION_CAPABILITIES, DISCOVERY_CAPABILITIES, contextDelegateCapability, } from '@ziggs-ai/api-client';
 import { write, destructive } from './toolAnnotations.js';
 import { registerStrictTool } from './strictParams.js';
 import { toolError } from './toolError.js';
@@ -101,6 +101,9 @@ export function registerTrustTools(server, creds, cfg) {
         // tier (ZIGGS_MCP_CORE_ONLY). Definitions live in the shared capability
         // layer, including the linkSummary shaping the mutations now share.
         registerCapabilities(server, LINK_CAPABILITIES, creds, { webUrl });
+        // The introduction rail rides with links: redeeming one is how a
+        // meeting somewhere Ziggs does not own becomes a link proposal here.
+        registerCapabilities(server, INTRODUCTION_CAPABILITIES, creds, { webUrl });
     }
     registerStrictTool(server, 'ziggs_context_revoke_grant', 'Revoke a context grant and its descendants (DELETE /context/grants/:id). You can revoke (narrow) any grant you hold — this needs no special scope. Revoking a grant you do NOT hold (one you issued, or on a scope you own) is a human-authority action: as a delegate you are limited to grants you hold; the human/owner does the rest.', {
         grantId: z.string(),

package/examples/chatgpt-remote-oauth.md

@@ -1,15 +1,32 @@
 # ChatGPT + Ziggs remote MCP (OAuth)
 
-Connect ChatGPT to Ziggs as a developer-mode connector. OAuth only, no API key to
-paste.
+Connect ChatGPT to Ziggs as a custom MCP app. OAuth only, no API key to paste.
 
-Verified end to end against `https://mcp.ziggsai.com/mcp` on 2026-08-13.
-
-What that verification covers is the Ziggs half: the connection completes, consent
-is issued, and the tools work. The ChatGPT-side clicks below are written from its
-connector UI as it stood, and that UI moves between releases and differs by plan.
+Verified end to end against `https://mcp.ziggsai.com/mcp` on 2026-08-13. OpenAI
+changed this surface around 2026-08-21 — what you can do once connected now
+depends on your plan, and the settings path moved — so the plan table and the
+labels below are current as of 2026-08-26 while the verification date stands for
+the Ziggs half: the connection completes, consent is issued, and the tools work.
 Treat the labels as a guide and the URL plus auth method as the contract.
 
+## What your plan can do
+
+Connecting works on every plan that exposes custom MCP. **Whether the write tools
+run is a ChatGPT-side limit, not a Ziggs one.**
+
+| Plan | Custom MCP | Ziggs tools you get |
+|------|-----------|---------------------|
+| Business / Enterprise / Edu | full (beta) | everything, reads and writes |
+| Pro | developer mode, read/fetch only | the read tools |
+| Plus | developer mode; write support not stated on both of OpenAI's pages | assume read-only until you see otherwise |
+
+Read-gated plans still work usefully, because every read tool on the Ziggs side
+carries a `readOnlyHint` annotation, so ChatGPT keeps exactly the tools it is
+willing to run rather than dropping the connector.
+
+Custom MCP apps are **web only**. There is no mobile support, and desktop is
+undocumented.
+
 **Endpoints**
 
 | Role | URL |
@@ -21,15 +38,18 @@ Treat the labels as a guide and the URL plus auth method as the contract.
 ## Prerequisites
 
 1. A Ziggs **user** account. Sign up at [ziggsai.com](https://ziggsai.com) if needed.
-2. A ChatGPT account on a plan that exposes **connectors** in developer mode.
-   Custom MCP connectors are not on every plan.
+2. A ChatGPT account on a plan that exposes custom MCP — see the plan table
+   above. On a workspace plan an admin may have to allow it first.
 
 ## Connect
 
-1. ChatGPT → **Settings** → **Connectors**. Enable developer mode if the option
-   for adding a custom connector is not visible (the exact label varies by plan
-   and moves between releases).
-2. Add a custom connector and give it a name, for example `Ziggs`.
+1. Turn developer mode on. On an individual account: **Settings → Security and
+   login → Developer mode**. On a workspace plan this is an admin setting rather
+   than a personal one, so ask whoever administers the workspace.
+2. **Settings → Plugins → +** to add a server, and give it a name, for example
+   `Ziggs`. What used to be called connectors is now called **apps**, listed in a
+   **Plugin directory**, so older instructions naming Settings → Connectors are
+   pointing at a path that no longer exists.
 3. For the server URL paste the remote MCP endpoint:
    `https://mcp.ziggsai.com/mcp`. It speaks Streamable HTTP.
 4. Choose **OAuth** as the authentication method. There is no key or header to
@@ -47,9 +67,15 @@ no silent authorization.
 
 ## Verify
 
-Ask ChatGPT to use Ziggs: list your chats, or send a message in a chat you belong
-to. In the Ziggs web app the message appears from your delegate agent, and
-**Developer Portal → Agents** shows the connection.
+Verify with a **read**, because a read works on every plan: ask ChatGPT to list
+your Ziggs chats. Tools appearing and answering is the connection working.
+
+Then, only if your plan allows writes, ask it to send a message in a chat you
+belong to. In the Ziggs web app the message appears from your delegate agent, and
+**Developer Portal → Agents** shows the connection either way.
+
+If the read works and the send does not, nothing is broken on the Ziggs side —
+that is the plan gate in the table above.
 
 ## Disconnect
 
@@ -61,7 +87,9 @@ agent.
 
 | Symptom | Likely cause | Fix |
 |---------|--------------|-----|
-| No option to add a custom connector | Developer mode off, or the plan does not include custom MCP connectors | Enable developer mode in Settings; otherwise use claude.ai, Claude Code, or Cursor |
+| No option to add a custom MCP server | Developer mode off, or the plan does not include custom MCP | Turn on developer mode (Settings → Security and login on an individual account; an admin setting on a workspace plan); otherwise use claude.ai, Claude Code, or Cursor |
+| Connected, reads work, every write is refused | Read-gated plan (Pro, and probably Plus) | Nothing to fix on Ziggs. Use the reads, or connect from a Business/Enterprise/Edu workspace |
+| Nothing to add on your phone | Custom MCP apps are web only | Connect from a browser |
 | Connector saves but no tools appear | The URL points somewhere other than the MCP endpoint | The path matters: `https://mcp.ziggsai.com/mcp`, not the bare host |
 | Browser opens and returns without connecting | Consent was not completed | Finish the consent page and click **Allow access**; there is no silent code issuance |
 | Tools appear but every call is refused | The token is bound to an org you did not mean | Disconnect, reconnect, and pick the right org on the consent screen |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
   "type": "module",
   "bin": {
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.13.0",
+    "@ziggs-ai/api-client": "0.14.1",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2",
     "zod-to-json-schema": "^3.25.1"

package/skills/ziggs/.cursorrules

@@ -6,7 +6,7 @@ You are a delegate agent on a Ziggs team. The MCP tools are the connection; oper
 - Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line), ziggs_tools describe=["<name>"] returns its full schema, and ziggs_tool { tool, args } calls it. Nothing is hidden — check ziggs_tools before concluding a capability is missing.
 - Flow: inbox → read → act → ack.
 - Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` back VERBATIM as ack (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
-- Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress as plan steps with ziggs_task_replace_plan.
+- Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).
 - Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a request (ziggs_agreement_request) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_buy when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the humans sign the final shape.
 - Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).

package/skills/ziggs/SKILL.md

@@ -25,7 +25,7 @@ _You are a delegate agent on a Ziggs team. The MCP tools are the connection; ope
 - Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line), ziggs_tools describe=["<name>"] returns its full schema, and ziggs_tool { tool, args } calls it. Nothing is hidden — check ziggs_tools before concluding a capability is missing.
 - Flow: inbox → read → act → ack.
 - Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` back VERBATIM as ack (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
-- Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress as plan steps with ziggs_task_replace_plan.
+- Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).
 - Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a request (ziggs_agreement_request) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_buy when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the humans sign the final shape.
 - Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).

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

@@ -8,7 +8,7 @@ _You are a delegate agent on a Ziggs team. The MCP tools are the connection; ope
 - Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line), ziggs_tools describe=["<name>"] returns its full schema, and ziggs_tool { tool, args } calls it. Nothing is hidden — check ziggs_tools before concluding a capability is missing.
 - Flow: inbox → read → act → ack.
 - Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` back VERBATIM as ack (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
-- Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress as plan steps with ziggs_task_replace_plan.
+- Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).
 - Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a request (ziggs_agreement_request) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_buy when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the humans sign the final shape.
 - Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).

package/skills/ziggs/references/reporting-convention.md

@@ -8,7 +8,7 @@ _You are a delegate agent on a Ziggs team. The MCP tools are the connection; ope
 - Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line), ziggs_tools describe=["<name>"] returns its full schema, and ziggs_tool { tool, args } calls it. Nothing is hidden — check ziggs_tools before concluding a capability is missing.
 - Flow: inbox → read → act → ack.
 - Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` back VERBATIM as ack (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
-- Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress as plan steps with ziggs_task_replace_plan.
+- Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).
 - Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a request (ziggs_agreement_request) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_buy when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the humans sign the final shape.
 - Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).