Postomator MCP: agent quickstart
These are factual connection instructions. Tool descriptions and schemas in the catalog are authoritative.
Discovery
endpoint: https://postomator.com/mcp
transport: streamable-http
protected_resource_metadata: https://postomator.com/.well-known/oauth-protected-resource/mcp
authorization_server_metadata: https://postomator.com/.well-known/oauth-authorization-server
json_catalog: /docs/mcp/catalog
plain_text_catalog: /docs/mcp/catalog.txtUse OAuth authorization code with S256 PKCE and the exact resource value advertised by protected-resource metadata. Host-managed connections perform this flow in the browser. Applications may supply a delegated bearer token acquired for this resource; do not use a Postomator API key.
Safe quickstart
- Review permissions and choose workspaces at first connection. All MCP permissions are requested by default; clients may explicitly request narrower access. Then list the authorized workspaces.
- Read the target workspace's drafts or calendar and confirm the intended workspace with the user.
- If the user asks to create a draft and content-write access is granted, call the catalog's dedicated draft-creation tool with explicit content and targets.
- Show the returned draft and state. Do not schedule, publish, invite, or delete unless the user requested it and the corresponding scope is granted.
Python MCP SDK 2.2.0
import asyncio
import httpx2 as httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
async def main():
async with httpx.AsyncClient(
headers={"Authorization": "Bearer <delegated-access-token>"}
) as http:
async with streamable_http_client("https://postomator.com/mcp", http_client=http) as streams:
async with ClientSession(*streams) as session:
await session.initialize()
print([tool.name for tool in (await session.list_tools()).tools])
asyncio.run(main())This low-level example assumes your application has already completed authorization-code OAuth and securely obtained the user token. Never put credentials in the URL or query string.
OpenAI Responses API
import OpenAI from "openai";
const response = await new OpenAI().responses.create({
model: "gpt-6-astra",
tools: [{
type: "mcp",
server_label: "postomator",
server_url: "https://postomator.com/mcp",
authorization: "<delegated-access-token>",
require_approval: "always"
}],
input: "List my Postomator drafts. Do not change anything."
});This is server-side API configuration with a pre-obtained user token, not the ChatGPT host connection flow. Applications choose the model and approval policy; keep approval enabled for sensitive calls. The authorization value is not a Postomator API key and must be supplied on each Responses request.
Companion transfers
Tools return instructions for post media multipart endpoints under /mcp/transfers, limited to 100 MiB. Audio transcription and transcription-to-draft, including audio upload endpoints, are not available through MCP. Standalone public/free tools, including CV generation, are also out of scope. Send bearer credentials only in the Authorization header. The ASGI edge or reverse proxy must enforce this ceiling because Django may spool a request body before view-level upload handlers run.
Repurposing and timezone
Use create_repurposing_content to submit an article, get_repurposing_content to poll its status and ideas, list_repurposing_content to find submitted content, and delete_repurposing_content to remove owned content and its ideas. Idea-to-draft and account text generation/editing remain available. get_queue includes timezone as read-only information from the shared workspace queue settings. Manual schedule_post uses the user's profile timezone; neither timezone can be changed through MCP.
Failures and retry
- HTTP 401 means the bearer token is absent, expired, or revoked; follow the protected-resource challenge and complete or refresh OAuth.
- HTTP 403 means the token lacks a scope or current workspace permission. Request only the missing access.
- Tool validation, domain, version, and eligibility failures are successful MCP transports with isError=true. Re-read current state before retrying a mutation. Companion transfer concurrency conflicts use HTTP 409.
- HTTP 429 includes Retry-After. The server permits 120 requests per user per minute (configurable with MCP_REQUESTS_PER_MINUTE); AI operations additionally permit 30 per user per hour.