How to use the Postoria MCP server

The Postoria MCP server lets MCP-compatible AI tools connect to Postoria through the Postoria Public API.

You can use it with local desktop tools through the npm package, or with hosted MCP clients through the Postoria hosted MCP endpoint.

The server can help an AI tool list workspaces, find social accounts and queues, import or upload media, publish posts, schedule posts, add posts to queues, check post status, and delete posts in Postoria.

MCP support depends on the AI tool you use. Common MCP-compatible tools include Claude Desktop, Cursor, Claude Code, and ChatGPT custom apps where custom MCP connections are available.

Before you start

Here are the main things to know before using the Postoria MCP server:

  • The MCP server uses the Postoria Public API.
  • Public API access is available on Pro and Agency plans.
  • You need a Postoria Public API key.
  • The API key is account-level, not workspace-level.
  • Local usage runs the MCP server on your machine through the npm package.
  • Hosted usage connects your MCP client to the Postoria hosted MCP endpoint.

You can also review the Postoria Public API help article for API key setup and API behavior.

Create a Public API key

  1. Open Postoria.
  2. Go to Settings.
  3. Find the Public API section.
  4. Click Create API key.
  5. Copy the key and store it securely.

Postoria shows the full API key only once. After closing the dialog, you will only see the key prefix.

If you lose the key, revoke it and create a new one.

Choose local or hosted usage

There are two main ways to use the Postoria MCP server.

Local usage

Use local mode when your MCP-compatible client can run a local command.

This is usually the best option for desktop or IDE tools such as Claude Desktop, Cursor, and Claude Code.

In local mode:

  • The MCP server runs through the npm package.
  • Your API key is provided through local MCP client configuration.
  • Desktop workflows can use the local file upload tool when supported by the MCP client.

The npm package is:

@postoria/mcp-server

The local command is:

npx -y @postoria/mcp-server

Hosted usage

Use hosted mode when your MCP-compatible client supports remote MCP servers and bearer token authentication.

This is usually the right option for hosted custom connectors, such as ChatGPT custom apps where custom MCP support is available.

In hosted mode:

  • You do not install the npm package locally.
  • Your MCP client connects to the Postoria hosted MCP endpoint.
  • Your API key is sent by the MCP client as a bearer token.

The hosted MCP endpoint is:

https://mcp.postoria.io/mcp

Use your Postoria Public API key as the bearer token.

Local MCP client configuration

The exact configuration depends on your MCP client.

For clients that support JSON-style MCP server configuration, use the package with your Postoria API key in the environment.

Example:

{
  "mcpServers": {
    "postoria": {
      "command": "npx",
      "args": ["-y", "@postoria/mcp-server"],
      "env": {
        "POSTORIA_API_KEY": "pst_live_your_postoria_api_key_here"
      }
    }
  }
}

After saving the configuration, restart or refresh your MCP client, then ask it to use Postoria.

Hosted MCP client configuration

For hosted MCP clients, use the hosted endpoint:

https://mcp.postoria.io/mcp

Choose an authentication option that sends an access token or API key as a bearer token.

The client should send your Postoria API key as:

Authorization: Bearer pst_live_your_postoria_api_key_here

If your client asks for the token value and separately asks for the header scheme, enter only the API key as the token value and choose Bearer as the scheme.

Do not paste the word Bearer into the token field unless your MCP client explicitly asks for the full header value.

After connecting, ask the client to scan or load the available tools.

Available tools

The Postoria MCP server provides tools for common publishing workflows.

Workspace and account tools

  • list_workspaces — list available Postoria workspaces.
  • list_social_accounts — list social accounts in a workspace.
  • list_queues — list queues in a workspace.

These tools help the AI client find the workspace, social account, and queue IDs it needs before creating a post.

Media tools

  • import_media_from_url — import media from a public URL.
  • create_media_upload — create a signed media upload URL.
  • complete_media_upload — complete a media upload after raw file bytes have been uploaded.
  • upload_media_from_file — upload a local file from the machine running the MCP server.
  • get_media — check media status and details.

Post tools

  • publish_post_now — publish a post immediately.
  • schedule_post — schedule a post for a specific time.
  • add_post_to_queue — add a post to a queue.
  • get_post — check post status and details.
  • delete_post — delete a post in Postoria. This does not remove already published content from social networks.

Media options

The right media workflow depends on where the media file is located.

Import media from a public URL

Use this when the image or video is already available through a public URL.

This is useful for media stored on a website, CMS, asset library, or another public source.

The AI client can call import_media_from_url, then call get_media to check whether processing has completed.

Upload media with a signed upload URL

Use this when the client can upload raw file bytes to a signed upload URL.

The flow is:

  1. Call create_media_upload.
  2. Upload the raw file bytes to the returned upload URL using PUT.
  3. Call complete_media_upload.
  4. Call get_media to check the media status.

Only call complete_media_upload after the raw file bytes have actually been uploaded.

Upload a local file

Use this in desktop MCP workflows when you want to upload a file by local path.

The AI client can call upload_media_from_file with a local file path. The MCP server uploads the file to Postoria, completes the upload, and returns the media status.

Example workflows

Example prompts should sound like normal publishing requests, not API instructions. The MCP client can decide which Postoria tools to call behind the scenes.

Find workspaces

Ask your MCP client:

Show me the Postoria workspaces I can access.

The client should list the available workspaces so you can choose where to work.

Find social accounts

Ask your MCP client:

Show the social accounts connected to the ACME Studio workspace.

The client should find the matching workspace first, then list the connected social accounts so you can choose where to publish.

Publish a text post

Ask your MCP client:

Publish this to the ACME Studio LinkedIn page: We just published a launch planning guide for small teams. It covers how to keep campaign assets, approvals, and scheduled posts organized before launch day.

Review the selected workspace, account, and post text before confirming the action.

Schedule a post

Ask your MCP client:

Schedule an Instagram post for ACME Studio tomorrow at 10:00 AM using the image I attached. Caption: A simple launch checklist can save hours when your team is preparing content across several channels.

The client should prepare the scheduled post and show you the selected account, media, and scheduled time before publishing is confirmed.

Add a post to a queue

Ask your MCP client:

Add this image post to the Weekly Tips queue for ACME Studio using the image I attached. Caption: Keep one reusable launch checklist for every campaign so your team knows what is approved, scheduled, and ready to publish.

The client should find the queue, prepare the post with the selected media, and add it to the selected publishing queue.

Safety and confirmation

AI clients can help prepare publishing actions, but you should still review important details before publishing or scheduling.

Before confirming a publishing action, check:

  • Workspace
  • Social accounts
  • Queues, if used
  • Caption
  • Media
  • Scheduled time and workspace time zone
  • Whether the action publishes now or schedules for later

delete_post deletes the matching post in Postoria. It does not remove content that has already been published on social networks. Use it only when you are sure the Postoria post should be deleted.

Source code and package

The Postoria MCP server is open source on GitHub:

https://github.com/postoria-app/postoria-mcp-server

The npm package is available here:

https://www.npmjs.com/package/@postoria/mcp-server