posterly-mcp-server 0.20.4 → 0.20.7

package/README.md

@@ -108,7 +108,7 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.20.4` exposes 58 tools.
+`posterly-mcp-server@0.20.7` exposes 58 tools.
 
 Public setup tools work before `POSTERLY_API_KEY` exists:
 
@@ -125,6 +125,7 @@ Authenticated tools require `POSTERLY_API_KEY`:
 - `get_connect_link`
 - `create_connect_session` (create a guided browser handoff for connecting a social account)
 - `get_connect_session` (poll connection progress while the user approves OAuth or enters credentials)
+- `create_api_key` (create a new API key after explicit confirmation; scopes cannot exceed the calling dashboard key)
 - `list_oauth_clients`
 - `create_oauth_client` (create a public PKCE client after explicit confirmation)
 - `update_oauth_client` (update redirect URIs/scopes after explicit confirmation)
@@ -140,7 +141,6 @@ Authenticated tools require `POSTERLY_API_KEY`:
 - `get_post`
 - `get_post_missing`
 - `ask_support` (authenticated docs-backed support with read-only account/post diagnostics; human tickets require explicit confirmation)
-- `get_support` (alias for `ask_support` for agents that look for get-style support tools)
 - `create_post` (supports `thread_posts: string[]` for X / Threads reply chains, plus `platform_settings` for platform-specific composer controls)
 - `create_posts_batch` (create up to 25 confirmed posts in one API request)
 - `update_post` (also accepts `platform_settings`)

package/dist/index.js

@@ -20,7 +20,7 @@ import { listPostsTool } from './tools/list-posts.js';
 import { uploadMediaTool } from './tools/upload-media.js';
 import { getPostTool } from './tools/get-post.js';
 import { getPostMissingTool } from './tools/get-post-missing.js';
-import { askSupportTool, getSupportTool } from './tools/ask-support.js';
+import { askSupportTool } from './tools/ask-support.js';
 import { updatePostTool } from './tools/update-post.js';
 import { updatePostStatusTool } from './tools/update-post-status.js';
 import { updatePostReleaseIdTool } from './tools/update-post-release-id.js';
@@ -56,6 +56,7 @@ import { uploadMediaFromUrlTool } from './tools/upload-media-from-url.js';
 import { getConnectLinkTool } from './tools/get-connect-link.js';
 import { createConnectSessionTool } from './tools/create-connect-session.js';
 import { getConnectSessionTool } from './tools/get-connect-session.js';
+import { createApiKeyTool } from './tools/create-api-key.js';
 import { listOAuthClientsTool } from './tools/list-oauth-clients.js';
 import { createOAuthClientTool } from './tools/create-oauth-client.js';
 import { updateOAuthClientTool } from './tools/update-oauth-client.js';
@@ -156,6 +157,15 @@ server.tool(getConnectSessionTool.name, getConnectSessionTool.description, getCo
         return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
     }
 });
+server.tool(createApiKeyTool.name, createApiKeyTool.description, createApiKeyTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await createApiKeyTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
 server.tool(listOAuthClientsTool.name, listOAuthClientsTool.description, listOAuthClientsTool.inputSchema.shape, async () => {
     try {
         const text = await listOAuthClientsTool.execute(client);
@@ -399,15 +409,6 @@ server.tool(askSupportTool.name, askSupportTool.description, askSupportTool.inpu
         return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
     }
 });
-server.tool(getSupportTool.name, getSupportTool.description, getSupportTool.inputSchema.shape, async (input) => {
-    try {
-        const text = await getSupportTool.execute(client, input);
-        return { content: [{ type: 'text', text }] };
-    }
-    catch (err) {
-        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
-    }
-});
 server.tool(updatePostTool.name, updatePostTool.description, updatePostTool.inputSchema.shape, async (input) => {
     try {
         const text = await updatePostTool.execute(client, input);

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

@@ -159,6 +159,34 @@ export type AskSupportPayload = {
     request_human?: boolean;
     confirm_escalation?: boolean;
 };
+export type ApiKeyScope = 'accounts:read' | 'accounts:write' | 'posts:read' | 'posts:write' | 'media:write' | 'analytics:read';
+export type CreateApiKeyPayload = {
+    name?: string;
+    scopes?: ApiKeyScope[];
+    workspace_id?: string;
+    expires_in_days?: number;
+    confirm: true;
+};
+export type CreateApiKeyResponse = {
+    key: string;
+    api_key: {
+        id: string;
+        name: string;
+        key_prefix: string;
+        scopes: ApiKeyScope[];
+        workspace_id?: string | null;
+        expires_at?: string | null;
+        created_at: string;
+    };
+    warning?: string;
+    limits?: {
+        tier?: string;
+        max_user_keys?: number;
+        active_user_keys?: number;
+        remaining_user_keys?: number;
+        uses_grandfathered_keys?: boolean;
+    };
+};
 export type AskSupportResponse = {
     success: boolean;
     workspace_id: string;
@@ -552,6 +580,7 @@ export declare class PosterlyClient {
     startSignup(data: PublicSignupPayload): Promise<PublicSignupResponse>;
     getSignupSession(sessionId: string): Promise<PublicSignupSessionResponse>;
     whoami(): Promise<Whoami>;
+    createApiKey(data: CreateApiKeyPayload): Promise<CreateApiKeyResponse>;
     listAccounts(params?: {
         workspace_id?: string;
     }): Promise<Account[]>;

package/dist/lib/api-client.js

@@ -113,6 +113,9 @@ export class PosterlyClient {
     async whoami() {
         return this.request('GET', '/whoami');
     }
+    async createApiKey(data) {
+        return this.request('POST', '/api-keys', data);
+    }
     async listAccounts(params) {
         const searchParams = new URLSearchParams();
         if (params?.workspace_id)

package/dist/lib/version.d.ts

@@ -1 +1 @@
-export declare const POSTERLY_MCP_VERSION = "0.20.4";
+export declare const POSTERLY_MCP_VERSION = "0.20.7";

package/dist/lib/version.js

@@ -1 +1 @@
-export const POSTERLY_MCP_VERSION = '0.20.4';
+export const POSTERLY_MCP_VERSION = '0.20.7';

package/dist/tools/ask-support.d.ts

@@ -34,37 +34,4 @@ export declare const askSupportTool: {
     }>;
     execute: typeof executeSupport;
 };
-export declare const getSupportTool: {
-    name: string;
-    description: string;
-    inputSchema: z.ZodObject<{
-        question: z.ZodString;
-        workspace_id: z.ZodOptional<z.ZodString>;
-        conversation_id: z.ZodOptional<z.ZodString>;
-        page_url: z.ZodOptional<z.ZodString>;
-        post_id: z.ZodOptional<z.ZodNumber>;
-        referenced_post_ids: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
-        request_human: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
-        confirm_escalation: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
-    }, "strip", z.ZodTypeAny, {
-        question: string;
-        workspace_id?: string | undefined;
-        post_id?: number | undefined;
-        conversation_id?: string | undefined;
-        page_url?: string | undefined;
-        referenced_post_ids?: number[] | undefined;
-        request_human?: boolean | undefined;
-        confirm_escalation?: boolean | undefined;
-    }, {
-        question: string;
-        workspace_id?: string | undefined;
-        post_id?: number | undefined;
-        conversation_id?: string | undefined;
-        page_url?: string | undefined;
-        referenced_post_ids?: number[] | undefined;
-        request_human?: boolean | undefined;
-        confirm_escalation?: boolean | undefined;
-    }>;
-    execute: typeof executeSupport;
-};
 export {};

package/dist/tools/ask-support.js

@@ -46,9 +46,3 @@ export const askSupportTool = {
     inputSchema: supportInputSchema,
     execute: executeSupport,
 };
-export const getSupportTool = {
-    name: 'get_support',
-    description: 'Alias for ask_support. Ask Posterly Support AI an authenticated question using Posterly docs plus read-only account/post diagnostics. Human tickets require request_human=true and confirm_escalation=true after explicit user confirmation.',
-    inputSchema: supportInputSchema,
-    execute: executeSupport,
-};

package/dist/tools/create-api-key.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import type { CreateApiKeyPayload, PosterlyClient } from '../lib/api-client.js';
+export declare const createApiKeyTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        scopes: z.ZodOptional<z.ZodArray<z.ZodEnum<["accounts:read", "accounts:write", "posts:read", "posts:write", "media:write", "analytics:read"]>, "many">>;
+        workspace_id: z.ZodOptional<z.ZodString>;
+        expires_in_days: z.ZodOptional<z.ZodNumber>;
+        confirm: z.ZodLiteral<true>;
+    }, "strip", z.ZodTypeAny, {
+        confirm: true;
+        workspace_id?: string | undefined;
+        name?: string | undefined;
+        scopes?: ("accounts:read" | "accounts:write" | "posts:read" | "posts:write" | "media:write" | "analytics:read")[] | undefined;
+        expires_in_days?: number | undefined;
+    }, {
+        confirm: true;
+        workspace_id?: string | undefined;
+        name?: string | undefined;
+        scopes?: ("accounts:read" | "accounts:write" | "posts:read" | "posts:write" | "media:write" | "analytics:read")[] | undefined;
+        expires_in_days?: number | undefined;
+    }>;
+    execute(client: PosterlyClient, input: CreateApiKeyPayload): Promise<string>;
+};

package/dist/tools/create-api-key.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { code, mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
+const scopeSchema = z.enum(['accounts:read', 'accounts:write', 'posts:read', 'posts:write', 'media:write', 'analytics:read']);
+function formatCreatedApiKey(result) {
+    const key = result.api_key;
+    return [
+        mdTitle('API key created'),
+        `Full key (shown once): ${code(result.key)}`,
+        mdSection('Details', mdKeyValue([
+            ['Name', key.name],
+            ['Key ID', code(key.id)],
+            ['Prefix', code(key.key_prefix)],
+            ['Scopes', key.scopes.join(', ')],
+            ['Workspace', key.workspace_id ? code(key.workspace_id) : 'all accessible workspaces'],
+            ['Expires', key.expires_at || 'no expiry'],
+            ['Remaining key slots', result.limits?.remaining_user_keys ?? 'unknown'],
+        ])),
+        mdSection('Warning', result.warning || 'Store this securely. It will not be shown again.'),
+    ].filter(Boolean).join('\n\n');
+}
+export const createApiKeyTool = {
+    name: 'create_api_key',
+    description: 'Create a new Posterly API key for the authenticated user. SECRET-CREATING WRITE: only use after explicit user confirmation. The new key can only request scopes already present on the calling dashboard-created API key; OAuth and managed assistant tokens cannot mint keys.',
+    inputSchema: z.object({
+        name: z.string().trim().min(1).max(120).optional().describe('Human-readable key name.'),
+        scopes: z.array(scopeSchema).min(1).max(6).optional().describe('Scopes for the new key. Omit to copy the calling key scopes. Cannot exceed the calling key scopes.'),
+        workspace_id: z.string().trim().min(1).optional().describe('Optional workspace restriction. Workspace-scoped calling keys cannot create keys outside their workspace.'),
+        expires_in_days: z.number().int().min(1).max(365).optional().describe('Optional expiry from now, up to 365 days. Omit for no expiry.'),
+        confirm: z.literal(true).describe('Must be true after the user explicitly confirms that a new secret API key should be created.'),
+    }),
+    async execute(client, input) {
+        const result = await client.createApiKey(input);
+        return formatCreatedApiKey(result);
+    },
+};

package/dist/tools/create-post.js

@@ -82,11 +82,11 @@ export const createPostPayloadInputSchema = z.object({
         .string()
         .optional()
         .describe('ISO 8601 datetime for scheduling (e.g. 2026-03-05T09:00:00Z). Omit for immediate publish.'),
-    media_url: z.string().optional().describe('URL of media to attach (image or video). For threads, attaches to the lead post only.'),
+    media_url: z.string().optional().describe('Media URL to attach. Posterly storage URLs are used as-is; third-party HTTP(S) URLs are copied into Posterly storage before the post is saved. Short-lived signed URLs must still be live when this tool runs. For threads, attaches to the lead post only.'),
     media_urls: z
         .array(z.string())
         .optional()
-        .describe('Multiple media URLs for carousel or multi-image posts. For TikTok, 2 or more images auto-create a photo slideshow (up to 35 images) and every image is posted.'),
+        .describe('Multiple media URLs for carousel or multi-image posts. Posterly storage URLs are used as-is; third-party HTTP(S) URLs are copied into Posterly storage before the post is saved. For TikTok, 2 or more images auto-create a photo slideshow (up to 35 images) and every image is posted.'),
     post_type: z
         .string()
         .optional()
@@ -156,6 +156,7 @@ export const createPostTool = {
         '4. If scheduling multiple posts in one turn, list every post first and confirm the batch as a whole, then prefer `create_posts_batch` so they are created in one API request.\n\n' +
         'AFTER CALLING: Tell the user the post was created, include the Posterly dashboard link returned by the tool, and offer the next natural action. Do not narrate raw HTTP, curl, or API plumbing.\n\n' +
         'Provide either account_id OR username+platform to identify the account. If scheduled_at is omitted, the post publishes immediately. If workspace_id is omitted, the server resolves one from the social account, falling back to the caller\'s default (personal) workspace - pass workspace_id explicitly if the user has more than one workspace.\n\n' +
+        'MEDIA URLS: Posterly storage URLs are used as-is. Third-party HTTP(S) media URLs are copied into Posterly storage before the post is saved, so API-created posts do not later fail on expired signed URLs. Short-lived signed URLs must still be live when this tool runs. You can also call `upload_media_from_url` first if you want to upload once and reuse the returned Posterly URL across posts.\n\n' +
         'THREADS: Pass `thread_posts` (an array of 2+ strings) to schedule a multi-post thread on X (Twitter) or Threads (Meta). The first entry is the lead post; the rest are published as replies in the same chain. X entries are capped at 280 characters each (4000 for verified, 25000 for organization accounts); Threads entries are capped at 500 characters each. When `thread_posts` is set, `caption` is ignored.\n\n' +
         'PLATFORM SETTINGS: Pass `platform_settings` for composer-equivalent controls: Facebook story/reel/backgrounds, YouTube title/privacy/thumbnail/playlist, LinkedIn document titles/mentions/video thumbnails, TikTok direct-post privacy/toggles/commercial disclosure, Pinterest post_type (image/video/carousel), board (from pinterest.boards helper), title, link, and cover_image_url (video Pins), GBP event/offer/CTA, X reply settings/polls, Threads reply controls/text attachments, Bluesky languages/alt text, and Instagram feed/story/reel/carousel/collaborators/first comments/trial Reels. `instagram_settings` remains as a backwards-compatible alias.\n\n' +
         'TIKTOK MEDIA: TikTok supports a single video or a photo slideshow of 1 to 35 images, never multiple videos. Image media auto-detects as a slideshow, so you usually do not set post_type or media_type for photos and every image is posted. Pass `platform_settings.media_type: "PHOTO"` to force a slideshow explicitly.',

package/dist/tools/update-post.js

@@ -67,8 +67,8 @@ export const updatePostTool = {
             .string()
             .optional()
             .describe('New scheduled time (ISO 8601, e.g. 2026-03-10T09:00:00Z)'),
-        media_url: z.string().optional().describe('New media URL'),
-        media_urls: z.array(z.string()).optional().describe('New media URLs for carousel'),
+        media_url: z.string().optional().describe('New media URL. Posterly storage URLs are used as-is; third-party HTTP(S) URLs are copied into Posterly storage before the post is saved. Short-lived signed URLs must still be live when this tool runs.'),
+        media_urls: z.array(z.string()).optional().describe('New media URLs for carousel. Posterly storage URLs are used as-is; third-party HTTP(S) URLs are copied into Posterly storage before the post is saved.'),
         post_type: z
             .string()
             .optional()

package/dist/tools/upload-media-from-url.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 export const uploadMediaFromUrlTool = {
     name: 'upload_media_from_url',
-    description: 'Fetch an image or video from a public HTTPS URL into posterly storage. Returns a URL that can be used with create_post.',
+    description: 'Fetch an image or video from a public HTTPS URL into Posterly storage. Returns a URL that can be used with create_post. You can also pass public HTTP(S) media URLs directly to create_post/update_post; use this tool when you want to upload once and reuse the returned Posterly URL.',
     inputSchema: z.object({
         url: z.string().url().describe('Public HTTPS URL for the image or video. Local/private network URLs are blocked.'),
         filename: z.string().optional().describe('Optional filename override.'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.20.4",
+  "version": "0.20.7",
   "description": "MCP server for posterly: schedule social media posts from Claude Desktop",
   "license": "MIT",
   "homepage": "https://www.poster.ly/mcp",

package/src/index.ts

@@ -21,7 +21,7 @@ import { listPostsTool } from './tools/list-posts.js';
 import { uploadMediaTool } from './tools/upload-media.js';
 import { getPostTool } from './tools/get-post.js';
 import { getPostMissingTool } from './tools/get-post-missing.js';
-import { askSupportTool, getSupportTool } from './tools/ask-support.js';
+import { askSupportTool } from './tools/ask-support.js';
 import { updatePostTool } from './tools/update-post.js';
 import { updatePostStatusTool } from './tools/update-post-status.js';
 import { updatePostReleaseIdTool } from './tools/update-post-release-id.js';
@@ -57,6 +57,7 @@ import { uploadMediaFromUrlTool } from './tools/upload-media-from-url.js';
 import { getConnectLinkTool } from './tools/get-connect-link.js';
 import { createConnectSessionTool } from './tools/create-connect-session.js';
 import { getConnectSessionTool } from './tools/get-connect-session.js';
+import { createApiKeyTool } from './tools/create-api-key.js';
 import { listOAuthClientsTool } from './tools/list-oauth-clients.js';
 import { createOAuthClientTool } from './tools/create-oauth-client.js';
 import { updateOAuthClientTool } from './tools/update-oauth-client.js';
@@ -210,6 +211,20 @@ server.tool(
   }
 );
 
+server.tool(
+  createApiKeyTool.name,
+  createApiKeyTool.description,
+  createApiKeyTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await createApiKeyTool.execute(client, input as any);
+      return { content: [{ type: 'text' as const, text }] };
+    } catch (err: any) {
+      return { content: [{ type: 'text' as const, text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
 server.tool(
   listOAuthClientsTool.name,
   listOAuthClientsTool.description,
@@ -588,20 +603,6 @@ server.tool(
   }
 );
 
-server.tool(
-  getSupportTool.name,
-  getSupportTool.description,
-  getSupportTool.inputSchema.shape,
-  async (input) => {
-    try {
-      const text = await getSupportTool.execute(client, input as any);
-      return { content: [{ type: 'text' as const, text }] };
-    } catch (err: any) {
-      return { content: [{ type: 'text' as const, text: `Error: ${err.message}` }], isError: true };
-    }
-  }
-);
-
 server.tool(
   updatePostTool.name,
   updatePostTool.description,

package/src/lib/api-client.ts

@@ -163,6 +163,43 @@ export type AskSupportPayload = {
   confirm_escalation?: boolean;
 };
 
+export type ApiKeyScope =
+  | 'accounts:read'
+  | 'accounts:write'
+  | 'posts:read'
+  | 'posts:write'
+  | 'media:write'
+  | 'analytics:read';
+
+export type CreateApiKeyPayload = {
+  name?: string;
+  scopes?: ApiKeyScope[];
+  workspace_id?: string;
+  expires_in_days?: number;
+  confirm: true;
+};
+
+export type CreateApiKeyResponse = {
+  key: string;
+  api_key: {
+    id: string;
+    name: string;
+    key_prefix: string;
+    scopes: ApiKeyScope[];
+    workspace_id?: string | null;
+    expires_at?: string | null;
+    created_at: string;
+  };
+  warning?: string;
+  limits?: {
+    tier?: string;
+    max_user_keys?: number;
+    active_user_keys?: number;
+    remaining_user_keys?: number;
+    uses_grandfathered_keys?: boolean;
+  };
+};
+
 export type AskSupportResponse = {
   success: boolean;
   workspace_id: string;
@@ -693,6 +730,10 @@ export class PosterlyClient {
     return this.request<Whoami>('GET', '/whoami');
   }
 
+  async createApiKey(data: CreateApiKeyPayload): Promise<CreateApiKeyResponse> {
+    return this.request('POST', '/api-keys', data);
+  }
+
   async listAccounts(params?: { workspace_id?: string }): Promise<Account[]> {
     const searchParams = new URLSearchParams();
     if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);

package/src/lib/version.ts

@@ -1 +1 @@
-export const POSTERLY_MCP_VERSION = '0.20.4';
+export const POSTERLY_MCP_VERSION = '0.20.7';

package/src/tools/ask-support.ts

@@ -53,11 +53,3 @@ export const askSupportTool = {
   inputSchema: supportInputSchema,
   execute: executeSupport,
 };
-
-export const getSupportTool = {
-  name: 'get_support',
-  description:
-    'Alias for ask_support. Ask Posterly Support AI an authenticated question using Posterly docs plus read-only account/post diagnostics. Human tickets require request_human=true and confirm_escalation=true after explicit user confirmation.',
-  inputSchema: supportInputSchema,
-  execute: executeSupport,
-};

package/src/tools/create-api-key.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import type { CreateApiKeyPayload, CreateApiKeyResponse, PosterlyClient } from '../lib/api-client.js';
+import { code, mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
+
+const scopeSchema = z.enum(['accounts:read', 'accounts:write', 'posts:read', 'posts:write', 'media:write', 'analytics:read']);
+
+function formatCreatedApiKey(result: CreateApiKeyResponse): string {
+  const key = result.api_key;
+  return [
+    mdTitle('API key created'),
+    `Full key (shown once): ${code(result.key)}`,
+    mdSection('Details', mdKeyValue([
+      ['Name', key.name],
+      ['Key ID', code(key.id)],
+      ['Prefix', code(key.key_prefix)],
+      ['Scopes', key.scopes.join(', ')],
+      ['Workspace', key.workspace_id ? code(key.workspace_id) : 'all accessible workspaces'],
+      ['Expires', key.expires_at || 'no expiry'],
+      ['Remaining key slots', result.limits?.remaining_user_keys ?? 'unknown'],
+    ])),
+    mdSection('Warning', result.warning || 'Store this securely. It will not be shown again.'),
+  ].filter(Boolean).join('\n\n');
+}
+
+export const createApiKeyTool = {
+  name: 'create_api_key',
+  description:
+    'Create a new Posterly API key for the authenticated user. SECRET-CREATING WRITE: only use after explicit user confirmation. The new key can only request scopes already present on the calling dashboard-created API key; OAuth and managed assistant tokens cannot mint keys.',
+  inputSchema: z.object({
+    name: z.string().trim().min(1).max(120).optional().describe('Human-readable key name.'),
+    scopes: z.array(scopeSchema).min(1).max(6).optional().describe('Scopes for the new key. Omit to copy the calling key scopes. Cannot exceed the calling key scopes.'),
+    workspace_id: z.string().trim().min(1).optional().describe('Optional workspace restriction. Workspace-scoped calling keys cannot create keys outside their workspace.'),
+    expires_in_days: z.number().int().min(1).max(365).optional().describe('Optional expiry from now, up to 365 days. Omit for no expiry.'),
+    confirm: z.literal(true).describe('Must be true after the user explicitly confirms that a new secret API key should be created.'),
+  }),
+
+  async execute(client: PosterlyClient, input: CreateApiKeyPayload) {
+    const result = await client.createApiKey(input);
+    return formatCreatedApiKey(result);
+  },
+};

package/src/tools/create-post.ts

@@ -86,11 +86,11 @@ export const createPostPayloadInputSchema = z.object({
     .string()
     .optional()
     .describe('ISO 8601 datetime for scheduling (e.g. 2026-03-05T09:00:00Z). Omit for immediate publish.'),
-  media_url: z.string().optional().describe('URL of media to attach (image or video). For threads, attaches to the lead post only.'),
+  media_url: z.string().optional().describe('Media URL to attach. Posterly storage URLs are used as-is; third-party HTTP(S) URLs are copied into Posterly storage before the post is saved. Short-lived signed URLs must still be live when this tool runs. For threads, attaches to the lead post only.'),
   media_urls: z
     .array(z.string())
     .optional()
-    .describe('Multiple media URLs for carousel or multi-image posts. For TikTok, 2 or more images auto-create a photo slideshow (up to 35 images) and every image is posted.'),
+    .describe('Multiple media URLs for carousel or multi-image posts. Posterly storage URLs are used as-is; third-party HTTP(S) URLs are copied into Posterly storage before the post is saved. For TikTok, 2 or more images auto-create a photo slideshow (up to 35 images) and every image is posted.'),
   post_type: z
     .string()
     .optional()
@@ -172,6 +172,7 @@ export const createPostTool = {
     '4. If scheduling multiple posts in one turn, list every post first and confirm the batch as a whole, then prefer `create_posts_batch` so they are created in one API request.\n\n' +
     'AFTER CALLING: Tell the user the post was created, include the Posterly dashboard link returned by the tool, and offer the next natural action. Do not narrate raw HTTP, curl, or API plumbing.\n\n' +
     'Provide either account_id OR username+platform to identify the account. If scheduled_at is omitted, the post publishes immediately. If workspace_id is omitted, the server resolves one from the social account, falling back to the caller\'s default (personal) workspace - pass workspace_id explicitly if the user has more than one workspace.\n\n' +
+    'MEDIA URLS: Posterly storage URLs are used as-is. Third-party HTTP(S) media URLs are copied into Posterly storage before the post is saved, so API-created posts do not later fail on expired signed URLs. Short-lived signed URLs must still be live when this tool runs. You can also call `upload_media_from_url` first if you want to upload once and reuse the returned Posterly URL across posts.\n\n' +
     'THREADS: Pass `thread_posts` (an array of 2+ strings) to schedule a multi-post thread on X (Twitter) or Threads (Meta). The first entry is the lead post; the rest are published as replies in the same chain. X entries are capped at 280 characters each (4000 for verified, 25000 for organization accounts); Threads entries are capped at 500 characters each. When `thread_posts` is set, `caption` is ignored.\n\n' +
     'PLATFORM SETTINGS: Pass `platform_settings` for composer-equivalent controls: Facebook story/reel/backgrounds, YouTube title/privacy/thumbnail/playlist, LinkedIn document titles/mentions/video thumbnails, TikTok direct-post privacy/toggles/commercial disclosure, Pinterest post_type (image/video/carousel), board (from pinterest.boards helper), title, link, and cover_image_url (video Pins), GBP event/offer/CTA, X reply settings/polls, Threads reply controls/text attachments, Bluesky languages/alt text, and Instagram feed/story/reel/carousel/collaborators/first comments/trial Reels. `instagram_settings` remains as a backwards-compatible alias.\n\n' +
     'TIKTOK MEDIA: TikTok supports a single video or a photo slideshow of 1 to 35 images, never multiple videos. Image media auto-detects as a slideshow, so you usually do not set post_type or media_type for photos and every image is posted. Pass `platform_settings.media_type: "PHOTO"` to force a slideshow explicitly.',

package/src/tools/update-post.ts

@@ -72,8 +72,8 @@ export const updatePostTool = {
       .string()
       .optional()
       .describe('New scheduled time (ISO 8601, e.g. 2026-03-10T09:00:00Z)'),
-    media_url: z.string().optional().describe('New media URL'),
-    media_urls: z.array(z.string()).optional().describe('New media URLs for carousel'),
+    media_url: z.string().optional().describe('New media URL. Posterly storage URLs are used as-is; third-party HTTP(S) URLs are copied into Posterly storage before the post is saved. Short-lived signed URLs must still be live when this tool runs.'),
+    media_urls: z.array(z.string()).optional().describe('New media URLs for carousel. Posterly storage URLs are used as-is; third-party HTTP(S) URLs are copied into Posterly storage before the post is saved.'),
     post_type: z
       .string()
       .optional()

package/src/tools/upload-media-from-url.ts

@@ -4,7 +4,7 @@ import type { PosterlyClient } from '../lib/api-client.js';
 export const uploadMediaFromUrlTool = {
   name: 'upload_media_from_url',
   description:
-    'Fetch an image or video from a public HTTPS URL into posterly storage. Returns a URL that can be used with create_post.',
+    'Fetch an image or video from a public HTTPS URL into Posterly storage. Returns a URL that can be used with create_post. You can also pass public HTTP(S) media URLs directly to create_post/update_post; use this tool when you want to upload once and reuse the returned Posterly URL.',
   inputSchema: z.object({
     url: z.string().url().describe('Public HTTPS URL for the image or video. Local/private network URLs are blocked.'),
     filename: z.string().optional().describe('Optional filename override.'),