Let your AI agent post to Mastodon

Can an AI agent post to Mastodon?

Postgale is the secure layer for AI agents on social media. This page covers Mastodon: what an agent can publish, what you need, the Mastodon rules Postgale applies, and how to connect an account on your server.

Mastodon is a network of independent servers. Postgale registers itself as an app on your server the first time someone connects from it, and you approve it on your server’s own page. After that the agent sends one plain request (the text, the media, the visibility, when to post) and Postgale uploads the media, waits for your server to process it and posts the status.

MCP (Model Context Protocol) is the open standard that lets AI assistants such as Claude and Cursor use outside tools. An MCP server is what they connect to. Postgale hosts one and a REST API, so ChatGPT, Claude, Cursor, VS Code, n8n or your own agent can post to Mastodon as a tool.

What do you need?

• A Mastodon account on any server (mastodon.social, hachyderm.io, your own instance...).
• A Postgale workspace, and a sign-in or an API key for the agent.
• Optional images or a video on a public HTTPS URL (upload them with upload_media).
• An AI tool that can call Postgale: ChatGPT, Claude, Cursor, n8n, VS Code, or your own code.

What can the agent do on Mastodon?

Which Mastodon rules does Postgale enforce?

• Text is counted the way your server counts it (links as 23 characters, remote mentions by username, content warnings included) against your server’s limit, usually 500.
• Media is uploaded with its alt text and the status waits until your server has processed it.
• Every status carries an idempotency key, so a retried request never posts twice.
• If you revoke Postgale under Authorized apps, the account is marked as needing reconnection and your webhook hears about it.
• When your server asks to slow down, Postgale waits until its limit resets before retrying.

How do I connect Mastodon to an AI agent with Postgale?

1. Create a Postgale workspace and open Dashboard → Accounts → Mastodon.
2. Enter your server’s domain (for @[email protected] that is hachyderm.io), sign in there and approve Postgale.
3. Connect your AI tool: add https://postgale.com/mcp in ChatGPT, Claude or Cursor and sign in to Postgale, or create a key under Dashboard → API keys for n8n or your own code.
4. Ask the agent for a draft first. Turn on approval in the dashboard if a person should sign off before anything goes live.

An agent can also start the connection itself: the connect_account tool (or GET /api/v1/connect/mastodon?instance=your.server) returns a sign-in link that is valid for 10 minutes and that the account owner opens in a browser. The agent never sees the password or the token.

What does a Mastodon post from an agent look like?

Ask your agent“Post our release notes to Mastodon as unlisted, with the screenshot and a good alt text, in English.”

{
  "content": "Release 2.4 is out: faster sync and dark mode. https://example.com/changelog",
  "platforms": [
    {
      "accountId": "acc_masto",
      "platformSpecificData": {
        "mediaUrl": "https://media.example.com/screenshot.png",
        "altText": "The new dashboard in dark mode",
        "visibility": "unlisted",
        "language": "en"
      }
    }
  ],
  "publishNow": true
}

Nothing has to go out unreviewed. Approval can be required per workspace, per connected account, per API key or per signed-in app; while it applies, posts wait as pending approval in the dashboard, and replies, direct messages and edits to live posts are refused. Every write the agent makes is kept in the audit log.

What can’t an agent do on Mastodon through Postgale?

• Edit a status (not supported yet); delete and post again instead.
• Read favourites, boosts or replies yet.
• Create polls.

Common questions