How to use the Postoria MCP server

The Postoria MCP server lets MCP-compatible AI tools create and manage posts in Postoria through the Postoria Public API.

You can connect to Postoria in two ways:

  1. Local npm MCP server — runs on your machine and uses your Postoria Public API key.
  2. Postoria hosted MCP endpoint — runs on Postoria infrastructure at https://mcp.postoria.io/mcp and supports OAuth sign-in or Public API key authentication, depending on what your MCP client supports.

The MCP 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, list existing posts, check post status, and delete posts in Postoria.

MCP support depends on the AI tool you use. MCP-compatible tools may 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:

  • MCP server access is available on Pro and Agency plans.
  • The MCP server uses the Postoria Public API behind the scenes.
  • The local npm MCP server requires a Postoria Public API key.
  • The Postoria hosted MCP endpoint can use OAuth sign-in when the MCP client supports OAuth discovery.
  • The Postoria hosted MCP endpoint can also accept a Postoria Public API key as a bearer token.
  • Public API keys are account-level, not workspace-level.
  • Local usage can upload local files from your machine when the MCP client supports file access.
  • The Postoria hosted MCP endpoint does not require installing the npm package locally.

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

Choose local or hosted usage

Choose the connection method that matches your MCP client.

Local npm MCP server

Use the local npm MCP server when your MCP-compatible client can run a local command.

This setup is common for desktop and IDE tools such as Claude Desktop, Cursor, and Claude Code.

In local mode:

  • The MCP server runs on your machine through the npm package.
  • Your Postoria Public API key is provided through local MCP client configuration.
  • Local file upload can work when the MCP client allows the MCP server to access a local file path.

The npm package is:

@postoria/mcp-server

The local command is:

npx -y @postoria/mcp-server

Postoria hosted MCP endpoint

Use the Postoria hosted MCP endpoint when your MCP-compatible client can connect to hosted MCP servers.

In hosted mode:

  • You do not install the npm package locally.
  • The MCP client connects to https://mcp.postoria.io/mcp.
  • OAuth-capable clients can guide you through Postoria sign-in.
  • Clients that support bearer tokens can use a Postoria Public API key.

The Postoria hosted MCP endpoint is:

https://mcp.postoria.io/mcp

Create a Public API key

Create a Public API key for the local npm MCP server or for hosted MCP clients that use bearer token authentication.

The OAuth sign-in flow for the Postoria hosted MCP endpoint does not use a Public API key.

To 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.

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 the 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.

Postoria hosted MCP endpoint

For hosted MCP connections, use this endpoint:

https://mcp.postoria.io/mcp

The hosted endpoint supports two authentication methods. The method you use depends on your MCP client.

OAuth sign-in

Some MCP clients support OAuth discovery for hosted MCP servers. In that case, add the Postoria hosted MCP endpoint in the MCP client and sign in to Postoria when prompted.

https://mcp.postoria.io/mcp

Public API key bearer token

Some MCP clients support custom bearer tokens. In that case, use your Postoria Public API key as a bearer token.

Authorization: Bearer pst_live_your_postoria_api_key_here

If the 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 the 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 local 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.
  • list_posts — list posts in a workspace with optional filters and pagination.
  • 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 and what your MCP client supports.

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 local 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 local 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.

List existing posts

Ask your MCP client:

Show scheduled Instagram posts in the ACME Studio workspace.

The client can use list_posts with filters such as account IDs, queue ID, post status, social networks, date range, result limit, and pagination cursor.

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