PostMantis - Agent-ready social publishing infrastructure

Standard MCP, same PostMantis auth

PostMantis exposes a standard remote MCP server at /mcp. It uses the same Bearer API keys, scopes, and resource visibility rules as the public HTTP API.

Use the MCP endpoint

Connect your MCP client to:

https://postmantis.com/mcp

Send the same API key you would use for the public API:

Authorization: Bearer <POSTMANTIS_API_KEY>

If your MCP client lets you configure extra headers, add the Bearer token there.

What the server exposes

The MCP server is intentionally thin. Tools map closely to the public API and preserve the same accepted-state semantics.

Read tools

MCP tool	Public API equivalent
`postmantis.health`	`GET /api/health`
`postmantis.list_profiles`	`GET /api/profiles`
`postmantis.get_profile`	`GET /api/profiles/{id}`
`postmantis.list_posts`	`GET /api/posts`
`postmantis.get_post`	`GET /api/posts/{id}`

Write tools

MCP tool	Public API equivalent
`postmantis.create_post`	`POST /api/posts`
`postmantis.update_post`	`PATCH /api/posts/{id}` semantics
`postmantis.publish_draft`	`POST /api/posts/{id}/publish`
`postmantis.cancel_post`	`POST /api/posts/{id}/cancel`
`postmantis.delete_draft`	`DELETE /api/posts/{id}`
`postmantis.create_media_asset`	`POST /api/uploads`
`postmantis.complete_media_asset`	`POST /api/uploads/{id}/complete`

Expect the same scope rules as the HTTP API

Read-only keys stay read-only

A read-only API key can use read tools only. Write tools return the same permission errors as the public API.

Profile and provider scope still applies

A scoped API key can only see or target posts and profiles inside that key's allowed providers and profiles.

Post visibility is still all-or-nothing

A key can read a post only when every delivery on that post is inside the key scope.

Manage API keys safely in MCP clients

Use a dedicated API key for each MCP client or automation instead of reusing one broad key everywhere.

A good setup usually looks like this:

use a read-only key unless the MCP client really needs to create, update, publish, cancel, or delete drafts
scope each key to the minimum providers and profiles it actually needs
keep separate keys for desktop assistants and production automations
store keys in environment variables, secret managers, or the MCP client's secret storage when available
never put long-lived keys in prompts, source code, screenshots, or shared docs
revoke and recreate a key if it is exposed in chat, logs, recordings, or other places you do not fully control

A simple naming pattern helps later when you need to rotate or revoke a key. For example:

claude-mcp-readonly
cursor-mcp-write-x
n8n-prod-publisher

Keys are instance-specific

A key created on one PostMantis deployment only works against that same deployment and database. Keep separate keys for staging and production.

Follow the normal publish flow

A good MCP workflow usually looks like this:

postmantis.list_profiles
postmantis.create_post
postmantis.publish_draft if you created a draft first
postmantis.delete_draft if you decide to discard a draft instead of publishing it
postmantis.get_post later to inspect deliveries[]

Accepted does not mean published

create_post and publish_draft are acceptance commands. They return the initial workflow state such as draft, pending, or scheduled. Read the post later to inspect final delivery results.

Use upload sessions or remote URLs for media

MCP tool arguments are JSON. That means raw multipart file uploads are not part of the MCP surface. For media, use one of these approaches instead:

reference a public remote URL
or create a media asset with postmantis.create_media_asset
upload the file to the returned URL
mark it complete with postmantis.complete_media_asset
reference the returned asset_id when creating or updating a post

In both cases the result is the same: PostMantis ingests accepted media into PostMantis-owned storage before downstream publishing runs.

What to inspect after publishing

Use postmantis.get_post after the workflow runs and inspect:

top-level post status
deliveries[] for per-profile outcomes
each delivery's final status, provider id, URL, and error details when present

completed does not mean every delivery succeeded

completed means PostMantis finished orchestrating the workflow. Always inspect deliveries[] to see which publish attempts succeeded or failed.

Wrapper rules

Keep request shapes honest

The MCP tools intentionally follow the public API shapes instead of inventing a hidden agent-only contract.

Prefer tool calls over custom prompts

Use tools for operational work. Prompts and resources can be added later without changing the core publish model.

Reuse the HTTP docs for semantics

If a field or status behaves a certain way in the HTTP API, expect the same behavior in MCP.

MCP Server