MCP for AI agents

Postless exposes a remote Model Context Protocol server so an AI client can create drafts, generate images, and schedule posts on your brands.

The dashboard stays the place you review work. MCP is the agent-facing adapter around the same public API. Create a draft first. Publish later only if you turn on posts:publish and ask the agent to publish that draft.

Typical flow:

create_post (draft)
        ↓
generate_post_media
        ↓
poll get_media_generation_status
        ↓
schedule_post

What you need

• An active Postless subscription and a verified email
• At least one finished brand (incomplete and archived brands are unreachable)
• An API key from Settings → API keys
• An MCP client that can call a remote Streamable HTTP server with a Bearer token

Create a key for MCP

1. Open Settings → API keys.

2. Name the key (for example Cursor or Claude).

3. Turn on the permissions the agent should have. For the demos below, use:

   Permission	Why
   brands:read	List brands and read voice profile
   brands:write	Update voice, audience, pillars, and related profile
   inbox:read	Browse notes and uploads already in the inbox
   posts:read	List posts and poll media generation
   posts:write	Create & update drafts, generate media, schedule
   plans:read	Read the content calendar

   Leave Publish posts off unless you want the agent to publish a draft you already created. Create and publish stay two steps. There is no create-and-publish-now tool.

4. Optionally limit the key to specific brands.

5. Click Create key and copy the secret. It is shown once.

The key is pl_…. Treat it like a password. Do not commit it to git.

Same subscription, media quotas, and 60 requests per 60 seconds as the public API apply. When the API key limit is hit, tool calls fail with 429 rate_limit_exceeded, a Retry-After header (seconds), and retryAfterSec in the error body — wait that long before retrying.

Endpoint

https://dashboard.postless.app/mcp

Transport: Streamable HTTP. Auth:

Authorization: Bearer pl_YOUR_KEY

x-api-key: pl_YOUR_KEY also works. On your own host, replace the domain with that host.

Tools

create_post is not AI generation. The client writes the caption. Use get_brand or the voice resource so the copy matches the brand.

update_post requires a postId (UUID). Take it from the user (shown under the title on the draft page), or from a prior create_post / list_posts / get_post result. Do not guess or search by topic text — that is ambiguous and can overwrite the wrong post.

platformVariants on create/update is keyed by providerAccountId from get_brand_social_accounts. Use it for different captions per connection (for example longer Threads, shorter X). Shared body remains the fallback.

Pinterest / YouTube extras on each variant:

get_brand_social_accounts returns pinterest.boards, defaultBoardIds, and defaultLink for Pinterest connections (set in the dashboard). Sending boardIds on create/update also adds unknown board ids to that catalog (name = id); it does not change defaults. Pins need exactly one image or video on the Pinterest account and at least one board. Instagram/Pinterest may omit caption when media is attached; other platforms still need body. Non-empty captions must still respect each platform’s character limit on schedule/publish.

generate_post_media does not invent a prompt. Pass type (image, video, or carousel) and a prompt (10–3000 characters). aspectRatio is optional (1:1, 4:5, 9:16, 16:9). Image and carousel default to 4:5; video defaults to 9:16. Then poll. Video and carousel can take minutes. Brand aiImagesEnabled / aiVideosEnabled and weekly media quota still apply. Prefer a single still or video for Pinterest (not a multi-image carousel).

schedule_post is the step that puts something on the public calendar. The post must be ready to schedule (connected accounts, platform media rules, character limits, caption when required). It does not publish now.

Resources

Read-only context:

postless://brands/{brandId}/voice

Tone, audience, pillars, and related voice-profile fields for that brand. An agent can write in the brand’s style without a custom integration per model. Use update_brand when the user asks to change the profile.

How agents should work

1. list_brands / get_brand (or read the voice resource) before writing.
2. get_brand_social_accounts when you need publishConnectionIds.
3. list_inbox_items when you want to reuse notes or uploads (inboxItemIds on create_post).
4. create_post with finished copy. Omit scheduledAt to keep a draft while media generates.
5. update_post with an explicit postId when the user wants copy or targets changed.
6. generate_post_media if the post needs a still, video, or carousel. Poll get_media_generation_status, then get_post to confirm media[].
7. schedule_post / update_post with scheduledAt only when the post is ready to schedule.
8. publish_post only when the user explicitly asks to publish that draft. Never create and publish in one step.

Connect Cursor

1. Create an API key as above.
2. Open Cursor Settings → MCP (or add a project file .cursor/mcp.json).
3. Add a Streamable HTTP server:

{
  "mcpServers": {
    "postless": {
      "url": "https://dashboard.postless.app/mcp",
      "headers": {
        "Authorization": "Bearer pl_YOUR_KEY"
      }
    }
  }
}

If your Cursor build supports env interpolation, keep the secret out of the file:

{
  "mcpServers": {
    "postless": {
      "url": "https://dashboard.postless.app/mcp",
      "headers": {
        "Authorization": "Bearer ${env:POSTLESS_API_KEY}"
      }
    }
  }
}

4. Restart MCP or reload Cursor. You should see tools such as list_brands and create_post.
5. Try: “List my Postless brands, then draft a LinkedIn post for the first one about this week’s shipping notes. Save it as a draft — don’t schedule yet.”

Do not put .cursor/mcp.json with a raw pl_ secret in a shared repo.

Connect Claude Code

claude mcp add --transport http postless https://dashboard.postless.app/mcp \
  --header "Authorization: Bearer pl_YOUR_KEY"

Then in a Claude Code session:

Turn the changes in this working tree into a LinkedIn announcement for my Postless brand. Save it as a draft, generate a 4:5 image from a prompt that matches the caption, and wait until the image is attached.

Claude Code can inspect git locally and call Postless for distribution.

Connect Claude Desktop

Claude Desktop often speaks stdio, not remote HTTP. Bridge with mcp-remote:

{
  "mcpServers": {
    "postless": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://dashboard.postless.app/mcp",
        "--header",
        "Authorization: Bearer pl_YOUR_KEY"
      ]
    }
  }
}

Config path is usually Claude → Settings → Developer → Edit Config (claude_desktop_config.json). Restart Claude Desktop after saving.

If a later Claude Desktop build supports Streamable HTTP URLs natively, use the same URL and Bearer header as Cursor.

Connect VS Code (Copilot / agent)

Add .vscode/mcp.json (workspace) or a user MCP config:

{
  "servers": {
    "postless": {
      "type": "http",
      "url": "https://dashboard.postless.app/mcp",
      "headers": {
        "Authorization": "Bearer pl_YOUR_KEY"
      }
    }
  }
}

Reload the window. In agent chat, ask it to list Postless brands or create a draft.

ChatGPT, Claude.ai, and other hosted connectors

Hosted MCP clients that speak OAuth (not a pasted API key) can connect to the same /mcp endpoint.

1. In the host, add a remote MCP server URL: https://dashboard.postless.app/mcp.
2. The client reads /.well-known/oauth-protected-resource and starts the authorization code + PKCE flow.
3. Sign in to Postless and approve scopes on /oauth/consent. Leave Publish posts off unless you want that client to publish existing drafts.
4. The host stores the access token. You do not paste a pl_ key.
5. To cut access later, open Settings → Connected apps in Postless and disconnect the client. Also remove it from the host’s apps/connectors list if you want it gone on that side too.

If the host says the connection already exists, do not create a second app. Remove Postless from that host’s Apps/connectors list, or reuse the existing one and refresh tools. Start a new chat after reconnecting — an old thread can keep an empty tool cache.

Cursor, Claude Code, Claude Desktop (mcp-remote), and VS Code can still use an API key. Both auth methods are v1.

initialize and tools/list do not require a token so hosts can scan tools before OAuth. Calling a tool still needs an API key or access token.

Dynamic client registration is on so older hosts can register themselves. Newer hosts that send a Client ID Metadata Document URL are accepted too.

Sample use cases

1. Cursor: ship notes → LinkedIn draft

You just merged a release. In Cursor:

Turn the changes in this release into a LinkedIn announcement for Postless. Match our brand voice. Save it as a draft and generate a simple product still. Do not schedule.

The agent should:

1. Read the diff or changelog locally
2. list_brands / get_brand (or postless://brands/{id}/voice)
3. create_post with a LinkedIn caption
4. generate_post_media (type: image) and poll until attached

You open Posts in Postless to edit, then schedule or publish.

2. Fill gaps in next week’s calendar

Look at next week’s Postless calendar. For empty days, draft LinkedIn posts in our voice and leave them as drafts.

The agent should:

1. get_content_calendar
2. get_brand
3. create_post for each gap (no scheduledAt until you say so)

If you want them on the calendar: “Schedule those drafts for 10:00 on each empty day.” That is schedule_post — confirm the times before it runs.

3. Repurpose what you already posted

List my LinkedIn posts from this month. Draft three new posts that continue the same themes. Save drafts only.

Uses list_posts (filter by date / status). There is no analytics tool yet, so the agent cannot rank “top performing” posts. It can read recent copy and write variations.

4. Founder agent with GitHub

An agent with an external GitHub MCP (or pasted release notes) and Postless MCP:

We shipped 2.4 today. Read the GitHub release, write LinkedIn and X drafts in our voice, attach a generated image to LinkedIn, and schedule LinkedIn for tomorrow 9:00.

GitHub MCP (or the dashboard GitHub shipping connection) supplies facts. Postless is distribution: voice, draft, image, schedule. You still own publish. Postless MCP does not install or query GitHub repos.

5. Image for an existing draft

Generate a 4:5 image for post POST_ID: a quiet laptop on a desk, no text on the image. Poll until it’s attached.

Needs posts:write and posts:read. If generation is disabled on the brand or the weekly image quota is used, the tool returns an error — fix that in brand settings or wait for the week to reset.

Limits and safeguards

• No create-and-publish. create_post never publishes. publish_post needs posts:publish and an existing draft the user asked to publish.
• update_post / schedule_post require postId. Published posts return 409 post_not_editable.
• Media generation uses the same providers, brand toggles, and weekly caps as the dashboard.
• Tenant isolation is the API key or OAuth token: one Postless user (and optional brand allowlist), not every account on the server.
• Idempotency and validation are the same as /api/v1.

Troubleshooting

Related

• Public API
• Connect GitHub for shipping context
• Scheduling
• Set up your brand profile
• Getting started