posterly-mcp-server 0.43.0 → 0.43.2

package/README.md

@@ -122,13 +122,13 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.43.0` exposes 90 tools.
+`posterly-mcp-server@0.43.2` exposes 90 tools.
 
 Public setup tools work before `POSTERLY_API_KEY` exists:
 
 - `get_mcp_status` (show the installed server version, latest npm version, MCP endpoint health, API auth health, and update guidance)
 - `get_agent_signup_info`
-- `start_signup` (start paid signup and return a Posterly checkout handoff URL)
+- `start_signup` (start paid signup and return a poll URL, browser Checkout fallback, and prepaid PaymentIntent fields when agent-card pay is enabled)
 - `get_signup_session` (poll checkout, payment, password, and agent-access status)
 
 Authenticated tools require `POSTERLY_API_KEY`:

package/dist/lib/api-client.d.ts

@@ -821,6 +821,26 @@ export interface PublicSignupPayload {
     api_addon?: boolean;
     return_path?: string;
     source?: string;
+    tos_accepted?: boolean;
+}
+export interface PublicSignupAgentPay {
+    enabled?: boolean;
+    method?: string;
+    credential_type?: string;
+    amount?: number;
+    currency?: string;
+    amount_display?: string;
+    payment_intent_id?: string;
+    client_secret?: string | null;
+    publishable_key?: string | null;
+    confirm_url?: string;
+    poll_url?: string;
+    checkout_redirect_url?: string;
+    pay_instructions?: string;
+    status?: string;
+    period?: Record<string, unknown>;
+    requires_tos_acceptance?: boolean;
+    [key: string]: unknown;
 }
 export interface PublicSignupSession {
     id: string;
@@ -837,6 +857,7 @@ export interface PublicSignupSession {
     checkout?: Record<string, unknown>;
     account?: Record<string, unknown>;
     billing?: Record<string, unknown>;
+    agent_pay?: PublicSignupAgentPay | null;
     links?: Record<string, unknown>;
     created_at?: string;
     updated_at?: string;
@@ -856,6 +877,7 @@ export interface PublicSignupResponse {
     links?: Record<string, unknown>;
     account?: Record<string, unknown>;
     billing?: Record<string, unknown>;
+    agent_pay?: PublicSignupAgentPay | null;
     [key: string]: unknown;
 }
 export interface PublicSignupSessionResponse {

package/dist/lib/version.d.ts

@@ -1 +1 @@
-export declare const POSTERLY_MCP_VERSION = "0.43.0";
+export declare const POSTERLY_MCP_VERSION = "0.43.2";

package/dist/lib/version.js

@@ -5,4 +5,4 @@
 // tool set (minus the intentional pre-auth signup tools that only this stdio
 // package exposes). `npm run check:mcp-parity` enforces both the version match
 // and the tool-list match, and runs in the pre-commit hook.
-export const POSTERLY_MCP_VERSION = '0.43.0';
+export const POSTERLY_MCP_VERSION = '0.43.2';

package/dist/tools/get-agent-signup-info.js

@@ -14,8 +14,8 @@ export const getAgentSignupInfoTool = {
             '',
             'Pre-auth tools:',
             '- get_mcp_status: checks the installed server version, latest npm version, MCP endpoint health, API auth health, and whether POSTERLY_API_KEY is configured.',
-            '- start_signup: starts paid signup and returns a Posterly checkout handoff URL plus a signup poll URL.',
-            '- get_signup_session: polls checkout, payment, password, and agent-access status.',
+            '- start_signup: starts paid signup and returns a signup poll URL, a browser Checkout fallback, and, when enabled, a prepaid PaymentIntent for a Link virtual card (credential_type: card).',
+            '- get_signup_session: polls payment, password, and agent-access status.',
             '',
             'After Posterly access is installed, onboard the user IN THIS chat (do not send them to /onboarding-v2):',
             '- whoami: confirm the paid account and read onboarding.next_step.',
@@ -30,9 +30,11 @@ export const getAgentSignupInfoTool = {
             '- Do not narrate raw curl, HTTP, JSON, API keys, or implementation details unless the user explicitly asks for debugging.',
             '',
             'Boundaries:',
-            '- The user pays in Stripe Checkout in their browser.',
+            '- Payment can be a one-time Link Agent Wallet virtual card (credential_type: card) on the prepaid PaymentIntent, or Stripe Checkout in the browser.',
+            '- Never send card numbers to posterly. Confirm the PaymentIntent with Stripe, or send checkout_redirect_url.',
             '- The user sets their Posterly password in their browser.',
             '- The user approves social OAuth in their browser.',
+            '- Publish approval stays with the user.',
             '- The AI should never ask for card details, Posterly passwords, social passwords, or OAuth codes.',
         ].join('\n');
     },

package/dist/tools/get-signup-session.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 export const getSignupSessionTool = {
     name: 'get_signup_session',
-    description: 'Poll a public Posterly signup session created by start_signup. Use this to narrate checkout, payment, password setup, and agent access status before a Posterly API key is installed. Keep updates user-facing; do not narrate raw HTTP, curl, or API plumbing.',
+    description: 'Poll a public Posterly signup session created by start_signup. Use this to narrate payment (Link virtual card or browser Checkout), password setup, and agent access status before a Posterly API key is installed. Keep updates user-facing; do not narrate raw HTTP, curl, or API plumbing.',
     inputSchema: z.object({
         session_id: z
             .string()
@@ -23,18 +23,25 @@ function formatSignupSession(session, includeRaw) {
     const checkoutUrl = stringFromRecord(session.links, 'checkout_url');
     const passwordUrl = stringFromRecord(session.links, 'password_setup_url');
     const completeUrl = stringFromRecord(session.links, 'complete_url');
+    const agentPay = session.agent_pay;
     const lines = [
         `Posterly signup session: ${session.id}`,
         `Status: ${session.status}`,
         session.status_message ? `Message: ${session.status_message}` : '',
         nextAction?.label ? `Next action: ${nextAction.label}` : '',
         nextAction?.description ? `Next action detail: ${nextAction.description}` : '',
+        agentPay?.amount_display ? `Agent pay amount: ${agentPay.amount_display}` : '',
+        agentPay?.payment_intent_id ? `PaymentIntent: ${agentPay.payment_intent_id}` : '',
+        agentPay?.status ? `PaymentIntent status: ${agentPay.status}` : '',
+        agentPay?.requires_tos_acceptance ? 'Terms acceptance required before client_secret is released.' : '',
+        agentPay?.client_secret ? `PaymentIntent client_secret: ${agentPay.client_secret}` : '',
+        agentPay?.confirm_url ? `Confirm URL: ${agentPay.confirm_url}` : '',
         checkoutRedirectUrl ? `Checkout handoff URL: ${checkoutRedirectUrl}` : '',
         checkoutUrl ? `Checkout URL: ${checkoutUrl}` : '',
         passwordUrl ? `Password setup URL: ${passwordUrl}` : '',
         completeUrl ? `Completion URL: ${completeUrl}` : '',
         '',
-        guidanceForStatus(session.status),
+        guidanceForStatus(session.status, Boolean(agentPay?.enabled || agentPay?.payment_intent_id), Boolean(agentPay?.requires_tos_acceptance)),
         session.agent_next_steps?.length
             ? `Agent next steps:\n${session.agent_next_steps.map((step, index) => `${index + 1}. ${step}`).join('\n')}`
             : '',
@@ -46,10 +53,15 @@ function stringFromRecord(record, key) {
     const value = record?.[key];
     return typeof value === 'string' ? value : null;
 }
-function guidanceForStatus(status) {
+function guidanceForStatus(status, agentPayAvailable = false, requiresTosAcceptance = false) {
     switch (status) {
         case 'checkout_pending':
-            return 'Tell the user checkout is still pending. Keep polling; do not ask for card details.';
+            if (agentPayAvailable && requiresTosAcceptance) {
+                return 'Payment is still pending on terms acceptance. Ask the user to explicitly confirm they accept the posterly terms at https://www.poster.ly/terms, then POST { "tos_accepted": true } to Confirm URL to receive client_secret, or send the user the Checkout handoff URL. Keep polling; never ask for card numbers.';
+            }
+            return agentPayAvailable
+                ? 'Payment is still pending. Confirm the prepaid PaymentIntent with a Link virtual card (credential_type: card), or send the user the Checkout handoff URL. Keep polling; never ask for card numbers.'
+                : 'Tell the user checkout is still pending. Keep polling; do not ask for card details.';
         case 'checkout_expired':
             return 'Tell the user checkout expired and offer to call start_signup again.';
         case 'payment_confirmed':

package/dist/tools/start-signup.d.ts

@@ -11,6 +11,7 @@ export declare const startSignupTool: {
         api_addon: z.ZodDefault<z.ZodBoolean>;
         return_path: z.ZodDefault<z.ZodString>;
         source: z.ZodDefault<z.ZodString>;
+        tos_accepted: z.ZodOptional<z.ZodBoolean>;
         debug: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         email: string;
@@ -21,6 +22,7 @@ export declare const startSignupTool: {
         source: string;
         debug?: boolean | undefined;
         name?: string | undefined;
+        tos_accepted?: boolean | undefined;
     }, {
         email: string;
         debug?: boolean | undefined;
@@ -30,6 +32,7 @@ export declare const startSignupTool: {
         api_addon?: boolean | undefined;
         return_path?: string | undefined;
         source?: string | undefined;
+        tos_accepted?: boolean | undefined;
     }>;
     execute(client: PosterlyClient, input: {
         email: string;
@@ -39,6 +42,7 @@ export declare const startSignupTool: {
         api_addon?: boolean;
         return_path?: string;
         source?: string;
+        tos_accepted?: boolean;
         debug?: boolean;
     }): Promise<string>;
 };

package/dist/tools/start-signup.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 const DEFAULT_RETURN_PATH = '/dashboard/api?api_signup=success';
 export const startSignupTool = {
     name: 'start_signup',
-    description: 'Start the public Posterly paid signup flow for a user before Posterly API access exists. Returns a Posterly checkout handoff URL and signup poll URL. The user must handle payment and password setup in the browser. Do not ask for card details or a Posterly password in chat.',
+    description: 'Start the public Posterly paid signup flow for a user before Posterly API access exists. Returns a signup poll URL, a browser Checkout fallback URL, and, when enabled, a prepaid PaymentIntent the agent can pay with a Link Agent Wallet virtual card (credential_type: card). The user still sets a password and approves social OAuth in the browser. Never ask for card numbers, a Posterly password, or social passwords in chat.',
     inputSchema: z.object({
         email: z
             .string()
@@ -32,6 +32,10 @@ export const startSignupTool = {
             .string()
             .default('posterly_mcp_pre_auth_signup')
             .describe('Source label for analytics and support diagnostics.'),
+        tos_accepted: z
+            .boolean()
+            .optional()
+            .describe('Set true only after the user has explicitly confirmed, in this conversation, that they accept the posterly terms at https://www.poster.ly/terms. Sending it here avoids a separate terms-confirmation step before client_secret is released.'),
         debug: z
             .boolean()
             .optional()
@@ -46,6 +50,7 @@ export const startSignupTool = {
             api_addon: input.api_addon ?? true,
             return_path: input.return_path ?? DEFAULT_RETURN_PATH,
             source: input.source ?? 'posterly_mcp_pre_auth_signup',
+            tos_accepted: input.tos_accepted,
         });
         return formatSignupStart(response, Boolean(input.debug));
     },
@@ -64,22 +69,50 @@ function formatSignupStart(response, includeRaw) {
     const completeUrl = response.complete_url || valueFromLinks(response, 'complete_url');
     const status = session?.status || response.status || 'checkout_pending';
     const message = session?.status_message || response.status_message;
+    const agentPay = response.agent_pay || session?.agent_pay;
     const lines = [
         'Posterly signup started.',
         sessionId ? `Signup session: ${sessionId}` : '',
         `Status: ${status}`,
         message ? `Message: ${message}` : '',
-        checkoutRedirectUrl ? `Checkout handoff URL: ${checkoutRedirectUrl}` : '',
+        agentPay?.amount_display
+            ? `Agent pay amount: ${agentPay.amount_display} ${String(agentPay.currency || 'usd').toUpperCase()}`
+            : '',
+        agentPay?.payment_intent_id ? `PaymentIntent: ${agentPay.payment_intent_id}` : '',
+        agentPay?.requires_tos_acceptance ? 'Terms acceptance required before client_secret is released.' : '',
+        agentPay?.client_secret ? `PaymentIntent client_secret: ${agentPay.client_secret}` : '',
+        agentPay?.confirm_url ? `Confirm URL: ${agentPay.confirm_url}` : '',
+        agentPay?.pay_instructions ? `Pay instructions: ${agentPay.pay_instructions}` : '',
+        checkoutRedirectUrl ? `Checkout handoff URL (browser fallback): ${checkoutRedirectUrl}` : '',
         checkoutUrl ? `Checkout URL: ${checkoutUrl}` : '',
         pollUrl ? `Poll URL: ${pollUrl}` : '',
         completeUrl ? `Completion URL: ${completeUrl}` : '',
         '',
         'Next steps for the AI agent:',
-        '1. Send the Checkout handoff URL to the user so they can pay securely in their browser. Use the raw Stripe checkout URL only if you preserve the full URL including any fragment. posterly does not email this link, so do not tell the user to check their inbox at this stage.',
-        '2. Call get_signup_session with the signup session ID until the status changes.',
-        '3. Tell the user when Posterly sends the password setup email.',
-        '4. If status becomes agent_access_required, ask the user to install or paste the Posterly MCP/API setup instructions into this trusted AI chat, then onboard them in this conversation (about you, connect, brand voice, first post). Do not send them to /onboarding-v2.',
-        '5. Do not ask for card details, the Posterly password, social passwords, or OAuth codes.',
+        ...(agentPay?.enabled && agentPay?.requires_tos_acceptance
+            ? [
+                '1. Ask the user to explicitly confirm they accept the posterly terms at https://www.poster.ly/terms.',
+                '2. Once confirmed, POST { "tos_accepted": true } to Confirm URL (optionally with payment_method in the same call) to receive client_secret.',
+                '3. If the user would rather pay on the website, send them the Checkout handoff URL instead.',
+                '4. Call get_signup_session with the signup session ID until the status changes.',
+                '5. Do not ask for card details, the posterly password, social passwords, or OAuth codes.',
+            ]
+            : agentPay?.enabled
+                ? [
+                    '1. Prefer agent_pay: confirm the PaymentIntent with a one-time Link Agent Wallet virtual card (credential_type: card). Never paste card numbers into chat or send them to posterly.',
+                    '2. If the user would rather pay on the website, send them the Checkout handoff URL instead.',
+                    '3. Call get_signup_session with the signup session ID until the status changes.',
+                    '4. Tell the user when Posterly sends the password setup email. Password, social OAuth, and publish approval stay in the browser.',
+                    '5. If status becomes agent_access_required, ask the user to install or paste the Posterly MCP/API setup instructions into this trusted AI chat, then onboard them in this conversation (about you, connect, brand voice, first post). Do not send them to /onboarding-v2.',
+                    '6. Do not ask for card details, the Posterly password, social passwords, or OAuth codes.',
+                ]
+                : [
+                    '1. Send the Checkout handoff URL to the user so they can pay securely in their browser. Use the raw Stripe checkout URL only if you preserve the full URL including any fragment. posterly does not email this link, so do not tell the user to check their inbox at this stage.',
+                    '2. Call get_signup_session with the signup session ID until the status changes.',
+                    '3. Tell the user when Posterly sends the password setup email.',
+                    '4. If status becomes agent_access_required, ask the user to install or paste the Posterly MCP/API setup instructions into this trusted AI chat, then onboard them in this conversation (about you, connect, brand voice, first post). Do not send them to /onboarding-v2.',
+                    '5. Do not ask for card details, the Posterly password, social passwords, or OAuth codes.',
+                ]),
         includeRaw ? `\nRaw signup response:\n${JSON.stringify(response, null, 2)}` : '',
     ];
     return lines.filter(Boolean).join('\n');

package/dist/tools/update-post.js

@@ -107,7 +107,7 @@ const platformSettingsSchema = z.object({
 }).passthrough();
 export const updatePostTool = {
     name: 'update_post',
-    description: 'Update a scheduled or draft post. DESTRUCTIVE WRITE - overwrites the existing post\'s caption/media/schedule. Cannot edit published or currently publishing posts.\n\n' +
+    description: 'Update a scheduled or draft post. DESTRUCTIVE WRITE - overwrites the existing post\'s caption/media/schedule. Cannot edit published or currently publishing posts. If a client has already approved the post, a caption edit reopens caption approval and a media or thumbnail edit reopens asset approval. A reschedule, account change or settings change cannot be attributed to one axis and reopens both.\n\n' +
         'REQUIRED BEFORE CALLING: Show the user a side-by-side of the CURRENT post (caption, scheduled time, media) and the PROPOSED changes, and get explicit confirmation ("yes update it", "apply those changes") before calling. Do not auto-edit posts based on a general instruction - each edit needs its own confirmation.',
     inputSchema: z.object({
         post_id: z.number().describe('The post ID to update'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.43.0",
+  "version": "0.43.2",
   "mcpName": "io.github.awpthorp/posterly",
   "description": "MCP server for posterly: schedule and publish social media posts across 18 platforms from any MCP client (Claude, ChatGPT, Cursor, Windsurf, Cline, and more)",
   "license": "MIT",

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.awpthorp/posterly",
   "title": "posterly",
   "description": "Validate, schedule, publish, and analyze social content across 18 platforms with posterly.",
-  "version": "0.43.0",
+  "version": "0.43.2",
   "websiteUrl": "https://www.poster.ly/mcp",
   "repository": {
     "url": "https://github.com/awpthorp/posterly",
@@ -14,7 +14,7 @@
     {
       "registryType": "npm",
       "identifier": "posterly-mcp-server",
-      "version": "0.43.0",
+      "version": "0.43.2",
       "transport": {
         "type": "stdio"
       },

package/src/lib/api-client.ts

@@ -850,6 +850,32 @@ export interface PublicSignupPayload {
   api_addon?: boolean;
   return_path?: string;
   source?: string;
+  // Set true only after the user has explicitly confirmed, in this
+  // conversation, that they accept the posterly terms. Sending it on this
+  // first call avoids a separate terms-confirmation round trip.
+  tos_accepted?: boolean;
+}
+
+export interface PublicSignupAgentPay {
+  enabled?: boolean;
+  method?: string;
+  credential_type?: string;
+  amount?: number;
+  currency?: string;
+  amount_display?: string;
+  payment_intent_id?: string;
+  client_secret?: string | null;
+  publishable_key?: string | null;
+  confirm_url?: string;
+  poll_url?: string;
+  checkout_redirect_url?: string;
+  pay_instructions?: string;
+  status?: string;
+  period?: Record<string, unknown>;
+  // True until the user has explicitly accepted the posterly terms. While
+  // true, client_secret and publishable_key are withheld.
+  requires_tos_acceptance?: boolean;
+  [key: string]: unknown;
 }
 
 export interface PublicSignupSession {
@@ -867,6 +893,7 @@ export interface PublicSignupSession {
   checkout?: Record<string, unknown>;
   account?: Record<string, unknown>;
   billing?: Record<string, unknown>;
+  agent_pay?: PublicSignupAgentPay | null;
   links?: Record<string, unknown>;
   created_at?: string;
   updated_at?: string;
@@ -887,6 +914,7 @@ export interface PublicSignupResponse {
   links?: Record<string, unknown>;
   account?: Record<string, unknown>;
   billing?: Record<string, unknown>;
+  agent_pay?: PublicSignupAgentPay | null;
   [key: string]: unknown;
 }
 

package/src/lib/version.ts

@@ -5,4 +5,4 @@
 // tool set (minus the intentional pre-auth signup tools that only this stdio
 // package exposes). `npm run check:mcp-parity` enforces both the version match
 // and the tool-list match, and runs in the pre-commit hook.
-export const POSTERLY_MCP_VERSION = '0.43.0';
+export const POSTERLY_MCP_VERSION = '0.43.2';

package/src/tools/get-agent-signup-info.ts

@@ -19,8 +19,8 @@ export const getAgentSignupInfoTool = {
       '',
       'Pre-auth tools:',
       '- get_mcp_status: checks the installed server version, latest npm version, MCP endpoint health, API auth health, and whether POSTERLY_API_KEY is configured.',
-      '- start_signup: starts paid signup and returns a Posterly checkout handoff URL plus a signup poll URL.',
-      '- get_signup_session: polls checkout, payment, password, and agent-access status.',
+      '- start_signup: starts paid signup and returns a signup poll URL, a browser Checkout fallback, and, when enabled, a prepaid PaymentIntent for a Link virtual card (credential_type: card).',
+      '- get_signup_session: polls payment, password, and agent-access status.',
       '',
       'After Posterly access is installed, onboard the user IN THIS chat (do not send them to /onboarding-v2):',
       '- whoami: confirm the paid account and read onboarding.next_step.',
@@ -35,9 +35,11 @@ export const getAgentSignupInfoTool = {
       '- Do not narrate raw curl, HTTP, JSON, API keys, or implementation details unless the user explicitly asks for debugging.',
       '',
       'Boundaries:',
-      '- The user pays in Stripe Checkout in their browser.',
+      '- Payment can be a one-time Link Agent Wallet virtual card (credential_type: card) on the prepaid PaymentIntent, or Stripe Checkout in the browser.',
+      '- Never send card numbers to posterly. Confirm the PaymentIntent with Stripe, or send checkout_redirect_url.',
       '- The user sets their Posterly password in their browser.',
       '- The user approves social OAuth in their browser.',
+      '- Publish approval stays with the user.',
       '- The AI should never ask for card details, Posterly passwords, social passwords, or OAuth codes.',
     ].join('\n');
   },

package/src/tools/get-signup-session.ts

@@ -4,7 +4,7 @@ import type { PosterlyClient, PublicSignupSession } from '../lib/api-client.js';
 export const getSignupSessionTool = {
   name: 'get_signup_session',
   description:
-    'Poll a public Posterly signup session created by start_signup. Use this to narrate checkout, payment, password setup, and agent access status before a Posterly API key is installed. Keep updates user-facing; do not narrate raw HTTP, curl, or API plumbing.',
+    'Poll a public Posterly signup session created by start_signup. Use this to narrate payment (Link virtual card or browser Checkout), password setup, and agent access status before a Posterly API key is installed. Keep updates user-facing; do not narrate raw HTTP, curl, or API plumbing.',
   inputSchema: z.object({
     session_id: z
       .string()
@@ -28,6 +28,7 @@ function formatSignupSession(session: PublicSignupSession, includeRaw: boolean):
   const checkoutUrl = stringFromRecord(session.links, 'checkout_url');
   const passwordUrl = stringFromRecord(session.links, 'password_setup_url');
   const completeUrl = stringFromRecord(session.links, 'complete_url');
+  const agentPay = session.agent_pay;
 
   const lines = [
     `Posterly signup session: ${session.id}`,
@@ -35,12 +36,22 @@ function formatSignupSession(session: PublicSignupSession, includeRaw: boolean):
     session.status_message ? `Message: ${session.status_message}` : '',
     nextAction?.label ? `Next action: ${nextAction.label}` : '',
     nextAction?.description ? `Next action detail: ${nextAction.description}` : '',
+    agentPay?.amount_display ? `Agent pay amount: ${agentPay.amount_display}` : '',
+    agentPay?.payment_intent_id ? `PaymentIntent: ${agentPay.payment_intent_id}` : '',
+    agentPay?.status ? `PaymentIntent status: ${agentPay.status}` : '',
+    agentPay?.requires_tos_acceptance ? 'Terms acceptance required before client_secret is released.' : '',
+    agentPay?.client_secret ? `PaymentIntent client_secret: ${agentPay.client_secret}` : '',
+    agentPay?.confirm_url ? `Confirm URL: ${agentPay.confirm_url}` : '',
     checkoutRedirectUrl ? `Checkout handoff URL: ${checkoutRedirectUrl}` : '',
     checkoutUrl ? `Checkout URL: ${checkoutUrl}` : '',
     passwordUrl ? `Password setup URL: ${passwordUrl}` : '',
     completeUrl ? `Completion URL: ${completeUrl}` : '',
     '',
-    guidanceForStatus(session.status),
+    guidanceForStatus(
+      session.status,
+      Boolean(agentPay?.enabled || agentPay?.payment_intent_id),
+      Boolean(agentPay?.requires_tos_acceptance),
+    ),
     session.agent_next_steps?.length
       ? `Agent next steps:\n${session.agent_next_steps.map((step, index) => `${index + 1}. ${step}`).join('\n')}`
       : '',
@@ -55,10 +66,15 @@ function stringFromRecord(record: Record<string, unknown> | undefined, key: stri
   return typeof value === 'string' ? value : null;
 }
 
-function guidanceForStatus(status: string): string {
+function guidanceForStatus(status: string, agentPayAvailable = false, requiresTosAcceptance = false): string {
   switch (status) {
     case 'checkout_pending':
-      return 'Tell the user checkout is still pending. Keep polling; do not ask for card details.';
+      if (agentPayAvailable && requiresTosAcceptance) {
+        return 'Payment is still pending on terms acceptance. Ask the user to explicitly confirm they accept the posterly terms at https://www.poster.ly/terms, then POST { "tos_accepted": true } to Confirm URL to receive client_secret, or send the user the Checkout handoff URL. Keep polling; never ask for card numbers.';
+      }
+      return agentPayAvailable
+        ? 'Payment is still pending. Confirm the prepaid PaymentIntent with a Link virtual card (credential_type: card), or send the user the Checkout handoff URL. Keep polling; never ask for card numbers.'
+        : 'Tell the user checkout is still pending. Keep polling; do not ask for card details.';
     case 'checkout_expired':
       return 'Tell the user checkout expired and offer to call start_signup again.';
     case 'payment_confirmed':

package/src/tools/start-signup.ts

@@ -6,7 +6,7 @@ const DEFAULT_RETURN_PATH = '/dashboard/api?api_signup=success';
 export const startSignupTool = {
   name: 'start_signup',
   description:
-    'Start the public Posterly paid signup flow for a user before Posterly API access exists. Returns a Posterly checkout handoff URL and signup poll URL. The user must handle payment and password setup in the browser. Do not ask for card details or a Posterly password in chat.',
+    'Start the public Posterly paid signup flow for a user before Posterly API access exists. Returns a signup poll URL, a browser Checkout fallback URL, and, when enabled, a prepaid PaymentIntent the agent can pay with a Link Agent Wallet virtual card (credential_type: card). The user still sets a password and approves social OAuth in the browser. Never ask for card numbers, a Posterly password, or social passwords in chat.',
   inputSchema: z.object({
     email: z
       .string()
@@ -36,6 +36,10 @@ export const startSignupTool = {
       .string()
       .default('posterly_mcp_pre_auth_signup')
       .describe('Source label for analytics and support diagnostics.'),
+    tos_accepted: z
+      .boolean()
+      .optional()
+      .describe('Set true only after the user has explicitly confirmed, in this conversation, that they accept the posterly terms at https://www.poster.ly/terms. Sending it here avoids a separate terms-confirmation step before client_secret is released.'),
     debug: z
       .boolean()
       .optional()
@@ -52,6 +56,7 @@ export const startSignupTool = {
       api_addon?: boolean;
       return_path?: string;
       source?: string;
+      tos_accepted?: boolean;
       debug?: boolean;
     },
   ) {
@@ -63,6 +68,7 @@ export const startSignupTool = {
       api_addon: input.api_addon ?? true,
       return_path: input.return_path ?? DEFAULT_RETURN_PATH,
       source: input.source ?? 'posterly_mcp_pre_auth_signup',
+      tos_accepted: input.tos_accepted,
     });
 
     return formatSignupStart(response, Boolean(input.debug));
@@ -84,23 +90,51 @@ function formatSignupStart(response: PublicSignupResponse, includeRaw: boolean):
   const completeUrl = response.complete_url || valueFromLinks(response, 'complete_url');
   const status = session?.status || response.status || 'checkout_pending';
   const message = session?.status_message || response.status_message;
+  const agentPay = response.agent_pay || session?.agent_pay;
 
   const lines = [
     'Posterly signup started.',
     sessionId ? `Signup session: ${sessionId}` : '',
     `Status: ${status}`,
     message ? `Message: ${message}` : '',
-    checkoutRedirectUrl ? `Checkout handoff URL: ${checkoutRedirectUrl}` : '',
+    agentPay?.amount_display
+      ? `Agent pay amount: ${agentPay.amount_display} ${String(agentPay.currency || 'usd').toUpperCase()}`
+      : '',
+    agentPay?.payment_intent_id ? `PaymentIntent: ${agentPay.payment_intent_id}` : '',
+    agentPay?.requires_tos_acceptance ? 'Terms acceptance required before client_secret is released.' : '',
+    agentPay?.client_secret ? `PaymentIntent client_secret: ${agentPay.client_secret}` : '',
+    agentPay?.confirm_url ? `Confirm URL: ${agentPay.confirm_url}` : '',
+    agentPay?.pay_instructions ? `Pay instructions: ${agentPay.pay_instructions}` : '',
+    checkoutRedirectUrl ? `Checkout handoff URL (browser fallback): ${checkoutRedirectUrl}` : '',
     checkoutUrl ? `Checkout URL: ${checkoutUrl}` : '',
     pollUrl ? `Poll URL: ${pollUrl}` : '',
     completeUrl ? `Completion URL: ${completeUrl}` : '',
     '',
     'Next steps for the AI agent:',
-    '1. Send the Checkout handoff URL to the user so they can pay securely in their browser. Use the raw Stripe checkout URL only if you preserve the full URL including any fragment. posterly does not email this link, so do not tell the user to check their inbox at this stage.',
-    '2. Call get_signup_session with the signup session ID until the status changes.',
-    '3. Tell the user when Posterly sends the password setup email.',
-    '4. If status becomes agent_access_required, ask the user to install or paste the Posterly MCP/API setup instructions into this trusted AI chat, then onboard them in this conversation (about you, connect, brand voice, first post). Do not send them to /onboarding-v2.',
-    '5. Do not ask for card details, the Posterly password, social passwords, or OAuth codes.',
+    ...(agentPay?.enabled && agentPay?.requires_tos_acceptance
+      ? [
+          '1. Ask the user to explicitly confirm they accept the posterly terms at https://www.poster.ly/terms.',
+          '2. Once confirmed, POST { "tos_accepted": true } to Confirm URL (optionally with payment_method in the same call) to receive client_secret.',
+          '3. If the user would rather pay on the website, send them the Checkout handoff URL instead.',
+          '4. Call get_signup_session with the signup session ID until the status changes.',
+          '5. Do not ask for card details, the posterly password, social passwords, or OAuth codes.',
+        ]
+      : agentPay?.enabled
+      ? [
+          '1. Prefer agent_pay: confirm the PaymentIntent with a one-time Link Agent Wallet virtual card (credential_type: card). Never paste card numbers into chat or send them to posterly.',
+          '2. If the user would rather pay on the website, send them the Checkout handoff URL instead.',
+          '3. Call get_signup_session with the signup session ID until the status changes.',
+          '4. Tell the user when Posterly sends the password setup email. Password, social OAuth, and publish approval stay in the browser.',
+          '5. If status becomes agent_access_required, ask the user to install or paste the Posterly MCP/API setup instructions into this trusted AI chat, then onboard them in this conversation (about you, connect, brand voice, first post). Do not send them to /onboarding-v2.',
+          '6. Do not ask for card details, the Posterly password, social passwords, or OAuth codes.',
+        ]
+      : [
+          '1. Send the Checkout handoff URL to the user so they can pay securely in their browser. Use the raw Stripe checkout URL only if you preserve the full URL including any fragment. posterly does not email this link, so do not tell the user to check their inbox at this stage.',
+          '2. Call get_signup_session with the signup session ID until the status changes.',
+          '3. Tell the user when Posterly sends the password setup email.',
+          '4. If status becomes agent_access_required, ask the user to install or paste the Posterly MCP/API setup instructions into this trusted AI chat, then onboard them in this conversation (about you, connect, brand voice, first post). Do not send them to /onboarding-v2.',
+          '5. Do not ask for card details, the Posterly password, social passwords, or OAuth codes.',
+        ]),
     includeRaw ? `\nRaw signup response:\n${JSON.stringify(response, null, 2)}` : '',
   ];
 

package/src/tools/update-post.ts

@@ -113,7 +113,7 @@ const platformSettingsSchema = z.object({
 export const updatePostTool = {
   name: 'update_post',
   description:
-    'Update a scheduled or draft post. DESTRUCTIVE WRITE - overwrites the existing post\'s caption/media/schedule. Cannot edit published or currently publishing posts.\n\n' +
+    'Update a scheduled or draft post. DESTRUCTIVE WRITE - overwrites the existing post\'s caption/media/schedule. Cannot edit published or currently publishing posts. If a client has already approved the post, a caption edit reopens caption approval and a media or thumbnail edit reopens asset approval. A reschedule, account change or settings change cannot be attributed to one axis and reopens both.\n\n' +
     'REQUIRED BEFORE CALLING: Show the user a side-by-side of the CURRENT post (caption, scheduled time, media) and the PROPOSED changes, and get explicit confirmation ("yes update it", "apply those changes") before calling. Do not auto-edit posts based on a general instruction - each edit needs its own confirmation.',
   inputSchema: z.object({
     post_id: z.number().describe('The post ID to update'),