Agent discovery

The safe discover, sign up, connect, validate, confirm, and schedule workflow for AI agents using posterly.

Last updated Oct 24, 2026Updated this week

posterly exposes a complete public discovery graph so an AI agent can understand the product before asking a user to configure credentials.

1. Discover posterly

Start with one of these public resources:

Public plugins and directories

  • Cursor community directory: MCP install link, two skills, and a setup command. Separate from the official Cursor Marketplace.
  • ClawHub: published OpenClaw skill.
  • Smithery: managed hosted MCP connection with your own posterly OAuth sign-in.
  • Glama: ownership-verified listing, tool catalog, and client install options.
  • Official MCP Registry: published posterly server metadata.
  • Public plugin repository: installable Claude Code plugin and Gemini CLI extension.

Add posterly in ChatGPT from the plugin listing. The short setup page is Add posterly in ChatGPT. The Claude directory submission is under review. The Muse directory application is submitted, with requirements still outstanding. Use the client setup guides for the custom connections available today. API and MCP access needs a posterly plan with API access. New accounts can start with a 7-day free trial: a card is required, you are charged on day 8 unless you start the paid plan sooner, and API and MCP use is limited during the trial.

Do not scrape the dashboard to infer capabilities. Use list_platforms (add view: "schema" for one platform's fields), or the OpenAPI contract for the current platform rules.

2. Start the free trial

New accounts start a 7-day free trial of a posterly plan plus the API add-on. A card is required, you are charged on day 8 unless you start the paid plan sooner, and API and MCP use is limited during the trial. After the trial, API and MCP access stays on the paid plan plus the API add-on. Send the user to agent signup, or use the public MCP signup tools before an API key exists.

The signup flow never returns an API key before the trial or billing is active. The user starts the 7-day free trial in Stripe checkout, then completes password setup and any provider authorization in their browser.

3. Authenticate and confirm identity

After the user supplies a dashboard-created API key or completes an approved OAuth handoff:

  1. call whoami;
  2. inspect the returned workspaces and scopes;
  3. call list_accounts;
  4. ask which account and workspace the user intends to operate.

Never print, log, or place an API key in a post payload.

4. Connect a social account when needed

If the required account is absent, create a connection session for the chosen platform. Give the user the returned connect_url and poll the session. Provider OAuth and credentials stay in the user's browser; the agent receives bounded status updates.

Credential-based platforms (telegram, bluesky, discord, wordpress, devto, hashnode, lemmy) can also be connected headlessly: call GET /api/v1/connect/{platform} (or MCP list_platforms with view: "connect_link") to discover the required credential_fields, then submit them with POST /api/v1/connect/{platform}/credentials (or MCP connect_account). Prefer scoped secrets such as app passwords, bot tokens, webhook URLs, and API tokens over primary passwords, and tell the user that any credential they share passes through the conversation.

5. Get media into posterly storage

Chat attachments never become MCP arguments. Pick a path that matches the client:

  • Small public URL: upload_media with url, or pass media_url on validate/create. Server fetch caps: about 5MB relay, 60MB hard cap. Large R2/S3 URLs fail with remote_media_too_large.
  • Small file as JSON: hosted upload_media (base64). This hits the Vercel ~4MB request body on /api/mcp and /api/v1/media/upload. Use it for small images only.
  • Large local file on a machine the agent can read: stdio upload_media with file_path, or create_signed_upload then PUT the bytes to upload_url. That PUT goes to object storage and does not hit the 4MB Vercel body. Plan video caps are Starter 500MB, Pro 750MB, Power 1GB, Agency 4GB.
  • ChatGPT web / Claude.ai: chat paperclips never reach MCP, and the model cannot PUT a laptop file. Call create_media_drop, send the user drop_url (https://www.poster.ly/drop/<token>, no dashboard login), wait, then list_media (optionally with drop_session_id), then validate/create. Accepted: JPEG, PNG, GIF, WebP, MP4, MOV, WebM, and PDF up to 50MB (a PDF is for LinkedIn document posts). HEIC is not accepted: export or convert it to JPG or PNG first. Plan video caps still apply. This is not create_signed_upload. Codex, Claude Code, and Cursor can still use file_path or create_signed_upload then PUT.

Then gather the final account, caption, schedule, media URL from the step above, post type, platform settings, and workspace. Then use either:

  • MCP validate_post; or
  • POST /api/v1/posts with "dry_run": true.

Dry-run performs the same normalization and platform validation as live create, but it does not create a post, copy remote media, consume post-item or storage quota, reserve X quota, emit webhooks, or enqueue publishing.

Third-party media can produce remote_media_not_materialized. This means the URL was checked but not copied; live create still performs storage copy and final byte validation.

6. Show the preview and obtain confirmation

Resolve validation errors and warnings. Show the user:

  • account and platform;
  • complete final caption or thread;
  • scheduled time in the user's timezone;
  • attached media;
  • platform settings;
  • target workspace.

Obtain explicit confirmation for that exact post. Validation is not permission to publish.

7. Schedule the live post

After confirmation, call MCP create_post with confirm: true, or make the live REST request with dry_run omitted. Reuse the validated payload. Return the post ID, status, schedule, and posterly dashboard link.

8. Report product issues or private telemetry (optional)

Keep these two paths separate:

  • Public product board: when the human asks to report a bug or suggest a feature, call MCP submit_product_feedback or POST /api/v1/feedback with confirm: true after they approve the title and category. This lands on the same board as the dashboard Feedback page (5 submissions/day per API key).
  • Private ops telemetry: after a concrete tool success, error, or abandoned workflow, call MCP submit_agent_feedback or POST /api/v1/agent-feedback. Do not use this for roadmap ideas, and never put secrets, prompts, captions, media URLs, or personal data in the payload.

Schemas and examples live in the OpenAPI document (ProductFeedbackRequest, AgentFeedbackRequest).

For complete field documentation, continue with the REST API, MCP, or CLI guide.

Previous
CLI
Next
Pay for posterly from an agent