> Discover all available Postdom documentation from the machine-readable index: https://postdom.com/llms.txt

Agent guidance · public package

# Operating brief

A human authorizes a remote OAuth connection without showing a key, or configures a local MCP connection with a workspace key. The agent reads status, hands authorization back to the human, discovers accounts, and reads the brief before planning.

Required configuration

## Use boundary

This page begins after a human authorizes a supported Postdom MCP connection. Remote OAuth does not require a visible key. For the local stdio guides below, an owner, admin or member creates a workspace key in Connect → Agents → Advanced: Use a workspace key and keeps the generated configuration private. Social authorization and accepted media delivery remain separate.

`17 hosted tools`

The hosted MCP server has 17 tools, including `create_slideshow` and `list_posts`. The pinned local helper, `@postdom/mcp@0.4.0`, has 14; the extra tools are not a prerequisite for the released workflow. Inspect the connected inventory and schemas.

`destination IDs`

The agent reads valid account IDs from `list_accounts` after human authorization.

`credential boundary`

Credentials remain inside the configured connection or environment and never enter chat.

`media delivery`

The environment supplies an accepted video URL through its separately provisioned media path.

Four current clients

## Client placement

Select the agent client and place the same operating brief in its project-level instruction surface. ChatGPT project instructions do not create a live MCP connection.

### Codex brief placement
1. Paste the MCP configuration generated in Postdom Agents → Advanced: Use a workspace key into Codex.
2. Add the operating brief to the project AGENTS.md file.
3. Ask Codex to check workspace status and read the Workspace Brief before planning.
Place the operating brief in: `AGENTS.md`
[Codex instruction-file documentation](https://github.com/openai/codex/blob/main/docs/agents_md.md)

### Claude brief placement
1. Before starting Claude Code, load POSTDOM_API_KEY into its private environment using your secret manager, then register Postdom with the command below.
2. Add the operating brief to the project CLAUDE.md file.
3. Ask Claude to check workspace status and read the Workspace Brief before planning.
Place the operating brief in: `CLAUDE.md`
[Claude Code memory documentation](https://docs.anthropic.com/en/docs/claude-code/memory)

### Cursor brief placement
1. Paste the MCP configuration generated in Postdom Agents → Advanced: Use a workspace key into Cursor.
2. Add the operating brief as a project rule for Postdom workflows.
3. Ask Cursor to check workspace status and read the Workspace Brief before planning.
Place the operating brief in: `.cursor/rules/postdom.mdc`
[Cursor project-rules documentation](https://cursor.com/docs/rules)

### ChatGPT brief placement
1. Do not paste Postdom's local MCP configuration into ChatGPT. Live tools require a supported remote MCP connection.
2. Add the operating brief to the project instructions.
3. Inspect the connected server's inventory and schemas. Proceed only when it exposes the tools needed for the authorized action; do not assume hosted parity with the released helper or current source.
Place the operating brief in: `Project instructions`
[ChatGPT MCP connector documentation](https://help.openai.com/en/articles/12584461)

### Operating brief

```text
Use Postdom only after a human has created the workspace and authorized a supported Postdom MCP connection. Remote OAuth authorizes the workspace without showing a key; a local stdio connection instead requires a workspace agent key from Connected apps → For developers. Read credentials only through that configured connection or environment. Never print them, paste them into chat, or commit them.

1. Discover the connected server's tools and inspect their schemas. The released helper's baseline is get_workspace_status, get_brief, get_digest, get_learning, list_accounts, connect_account, upload_media, get_media, publish_video, submit_plan, get_plan, get_publish, get_performance, get_best_posts. Current source, which the hosted server at https://api.postdom.com/mcp runs, also defines list_posts, create_slideshow and account_music; they are absent from the released helper and are not prerequisites for the bounded workflow below. Use the tools the connected server actually lists. If a tool needed for the requested action is missing, stop that action and ask the human for a supported connection or manual handoff. For Codex, Claude Code, or Cursor, the exact local configuration shown in Connected apps → For developers uses the public package @postdom/mcp@0.4.0 and requires Node.js 22 or newer. ChatGPT project instructions do not connect this local server; live ChatGPT tools require a supported remote MCP connection. Never invent a credential or server URL.
2. Inspect the tool schemas before calling them. The configured publish_video schema accepts an optional publish_at UTC datetime. Never invent platform settings or any other argument the connected schema does not expose.
3. Call get_workspace_status first. If connections are locked, stop and return its exact connection-gate detail to the human. If connections are unlocked but no destinations are connected, call connect_account for the requested platform and give its authorization URL to the human. Never enter or handle the human's social credentials.
4. After the human completes authorization, call list_accounts and use only its returned account IDs. Do not guess, reuse an ID from another workspace, or claim connection succeeded before it appears.
5. Call get_brief before planning or writing content. Follow its advisory brand guidance and retain the returned version. Pass brief_version to submit_plan whenever plan-level review is used.
6. Read get_learning before planning to see what has already been observed on the account. Treat advice as exploratory.
7. Before submit_plan, call get_digest and read the prior plan's outcome through get_plan when one exists. Treat both as descriptive evidence of what happened, never as a recommendation. Read workspace and account policy before creating approval work. If plan-level review is required, use submit_plan for the bounded account set, time window, objective, maximum post count, and intent. Poll get_plan with exponential backoff, starting at 30 seconds and capping at 2 minutes. Stop after 10 minutes and give the human the plan ID if it is still pending.
8. When the finished video is not already at an accepted URL, call upload_media with its exact content type, byte length, target platforms, and measured dimensions and duration. The released helper requires all six fields; if target platforms are unknown, stop and ask the human. Optional-platform behavior in newer source is not the released contract. PUT the bytes directly to the returned short-lived URL using the returned method and headers. Never send bytes through MCP, change the object key, reuse an expired URL, or expose the signed URL. Call get_media until it returns stored; stop and preserve pending or failed exactly.
9. Use publish_video only with fields accepted by its connected schema. For the released video workflow, provide exactly one of video_url or the stored media_handle. Current source also exposes surface, title and description; do not send these unless the connected schema supports them. Its schema advertises exactly one top-level source: video_url, media_handle or media, with each media item naming exactly one media_url or media_handle. The corrected source adapter forwards ordered media in synthetic contract tests; this is not proof of a published npm release, hosted deployment or provider publication. The pinned @postdom/mcp@0.4.0 release is unchanged. The hosted server at https://api.postdom.com/mcp runs current source and accepts media; the pinned release does not, so send media only when the connected schema lists it. TikTok takes several images as a photo post. Include the approved plan ID when the work is plan-backed and, when exact-time scheduling is intended, an RFC 3339 UTC publish_at value ending in Z. Never guess a timezone. Obtain the human's review of the actual media, audience, disclosures and destination settings before submitting. Fixed consent or disclosure flags do not establish human preview or express consent; stop if the adapter defaults do not fit the intended post.
10. For any submitted plan, keep polling requires_approval and proceed only after approved. For changes_requested, rejected, expired, or cancelled, stop and return the exact state and plan ID to the human.
11. Poll get_publish with exponential backoff, starting at 15 seconds and capping at 2 minutes. Continue polling scheduled or publishing. Stop after 15 minutes and give the human the post ID if any destination is still nonterminal.
12. If get_publish returns draft, requires_approval, changes_requested, rejected, missed_approval, missed_schedule, partial, or failed, return the exact state and post ID to the human. Never rename a wire state to action_required, approve yourself, or expand trust.
13. Read get_performance after published or partial. After failed, read measurement eligibility and any available evidence. Preserve null values and availability states. Never and unverified nulls retain an explicit reason; other nulls may not.
14. Use get_best_posts only with an exact account ID, supported metric, and 7d or 30d window. Preserve excluded observations and their availability reasons; never rank missing evidence as zero.
15. Use the returned execution and measurement evidence when planning the next schedule.

If the workspace is missing, a human can create one at https://app.postdom.com/signup. The human creates and may revoke workspace agent keys in Connected apps → For developers.
```

Schedule to measurement

## Brief behavior

1. START get_workspace_status Read the connection gate and current setup progress before doing anything else.
2. HANDOFF connect_account Give the authorization URL to the human; never handle their social credentials.
3. DISCOVER list_accounts Use only destination IDs returned for this workspace.
4. BOUND get_brief Read advisory guidance before planning or writing content.
5. LEARN get_digest Before a new plan, read the completed week and the prior plan outcome as descriptive evidence only.
6. RETURN states Preserve exact wire states and return exceptions to the human supervisor.
7. MEASURE evidence Preserve zero, null, availability states, and guaranteed reasons exactly.
8. COMPARE get_best_posts Rank only available account metrics and preserve every excluded post reason.

The operating brief is agent guidance, not a callable schema. The connected schemas remain authoritative.

Editorial recommendations

## Polling guidance

These intervals are recommendations from the reviewed operating brief. They are not enforced by the configured tool contract.

`plan state`

Start at 30 seconds, cap at two minutes, and stop after ten minutes.

`publish state`

Start at 15 seconds, cap at two minutes, and stop after fifteen minutes.

`handoff`

Return the plan or post ID when the recommended polling window ends.

`global pause`

If `agent_paused` is returned, stop write activity and hand control to a human. Only a human can resume it.

Human handoff

## Missing access

### Stop and return

Stop when a tool, account ID, accepted media URL, credential, or human decision is missing. Do not invent a setup path.

 Documentation reviewed · 21 September 2026  **Released helper and current source distinguished; no authenticated publishing test**

Client instruction surfaces may change. Follow the linked primary client documentation when placement differs.