Build an agent on Postfjord

This guide is for you if you are building an agent, a GPT or an automation that works in Postfjord for someone. It uses the MCP tool names. Each one has a REST twin in the API reference, so the same steps work over plain HTTP.

The short version: read before you write, write drafts freely, and ask the person before anything goes out.

Connect

Point your agent at https://mcp.postfjord.com/mcp. Apps that open a browser sign in with OAuth, and the person picks the workspace and the level. Code that cannot sign in sends a key from Settings, Apps as Authorization: Bearer pf_live_.... The MCP help page has the steps for each app.

If you build for Claude Code or an agent that reads skills, install the postfjord skill from GitHub. It already holds the rules on this page.

The first three calls

1. postfjord_list_channels: the channel ids to post to, and each channel's limits: text length, hashtags, whether links work in the text, and the picture shapes.
2. postfjord_get_brand_profile: the voice, the audience, the do and do not rules and the content pillars. Read it before you write a word.
3. postfjord_list_calendar for the coming weeks: what is already planned, so you fill gaps and never double a day.

When a connection covers several workspaces, postfjord_list_workspaces lists them. Name the workspace in each call, and check with the person when they did not say which.

The post loop

1. Write the text yourself, in the brand voice, within the channel's limits.
2. Add pictures: postfjord_list_media for what is in the library, or postfjord_upload_media with a public https link.
3. Check: postfjord_create_draft with dry_run: true saves nothing and lists the problems per channel.
4. Save a draft: postfjord_create_draft without a time. A draft never goes out on its own, so you need no yes for it.
5. Show the pictures: postfjord_preview_post returns the exact picture each channel will send. Show them, and fix a crop that cuts off a face or words with a whole fit or a new focus.
6. Ask, then schedule: say the time back in the person's own time zone, and after a yes call postfjord_schedule_post.
7. Confirm: after the time, postfjord_get_post shows each channel's status and link, and postfjord_get_publish_log shows every attempt and its error.

postfjord_publish_now skips the clock and posts at once to the real accounts. It cannot be undone, so use it only when the person asks for it.

Recipes

A week of posts. Read the calendar for the week, pick days with nothing on them, write one draft per day and channel, then show the whole week in one message: day, time, channel, the first line and the picture. Schedule them only after a yes, all at once.

Move a week. Use postfjord_bulk_update_posts with reschedule and a shift, one call for up to 200 posts, instead of one update per post.

Did it work? postfjord_get_analytics gives followers, reach, likes and the best hours per channel. postfjord_get_weekly_signals gives twelve weeks side by side. Never guess a number that these did not return.

The Inbox. postfjord_list_conversations finds who is waiting, postfjord_draft_reply writes an answer and sends nothing. Show the exact text, and call postfjord_send_reply only after a yes.

One idea everywhere. postfjord_repurpose_idea turns one idea or a blog post into a draft for every channel and an email draft. It uses the workspace's AI budget, so prefer writing the posts yourself when you can.

Ask the person first

Always before any of these, in plain words about what will happen: publishing or scheduling a post, scheduling an email, sending a reply, switching an automation on, publishing a landing page, launching a Flow, and any delete. Everything that makes a draft needs no yes.

When a call fails

• Timeouts: every tool that makes or sends something takes an idempotency_key. Send the same key on the retry and the first answer comes back. Nothing is made twice. A new action needs a new key.
• 403: the answer names the level the connection lacks. Tell the person, who can reconnect with a higher level. Never work around it.
• 429: more than 60 calls a minute, or the AI budget is spent. Wait a minute, or write the text yourself.
• Times: a time without a time zone is refused. Send 2026-11-03T09:00:00-05:00, never 2026-11-03 09:00.
• Messages: pass Postfjord's message to the person as it is. It is written for them.

What an agent cannot do

No tool reaches billing, the plan, team members, API keys or the connected social accounts, and none removes a post that already went out. Every call is checked against the person's role in the workspace, so an agent can never do more than the person who connected it.