Publish from a coding agent
Connect Codex or Claude Code, upload a local file and verify a scheduled or published post without moving your work into another app.
You have a product photo on your computer and want to publish it to your brand’s Instagram account. Your coding agent can prepare the draft, upload the original file and request publication through HeyMark.
You need a HeyMark account with content access to the brand, a connected social account, and a client that can read the local file and make HTTP requests. A file on your computer is not automatically available to a remote chat session.
Connect your client
For Codex, run:
codex mcp add heymark --url https://mcp.heymark.aiIf authorization is still needed, run codex mcp login heymark. Approve access with your own HeyMark account in the browser. The browser is used for authorization; file transfer happens in the environment that can read your file.
For Claude Code, run:
claude mcp add --transport http heymark https://mcp.heymark.aiComplete the client’s OAuth flow. For other clients, use the connection guide. HeyMark MCP access is free on every plan. Product limits and metered AI work still apply, and your client may charge separately.
Choose the brand and prepare the draft
Ask your client to refresh its tool list, then use list_brands and get_brand_context. Choose the brand explicitly if you have several. Follow the schemas returned by tools/list; permissions and client support determine which tools you can use.
Prepare a draft
List my HeyMark brands and ask which one to use. For that brand, check the connected Instagram account. Prepare a draft announcing our new product, using the photo at [absolute file path] and this brief: [your brief]. Show me the caption, destination and media before scheduling or publishing anything.
create_post creates planning content. A planning date is not a publishing schedule. To reuse saved content, use duplicate_post and inspect the returned media state; a copy can still be importing files. Save the new post_id and reuse it for the rest of the workflow.
Upload the local file
Coding clients use prepare_post_media_upload, followed by attach_post_media. The preparation tool needs an existing post with a destination and the file’s MIME type and byte size. It returns an upload object and upload_instructions.
- Have your agent read the original file in its own environment and request the upload grant.
- Follow the returned resumable TUS instructions: create the upload with POST, then PATCH the original bytes to the returned location in the requested chunks. Do not paste the file as base64 into the conversation. Base64 is only used for the TUS metadata values.
- Attach the file only after the server’s
Upload-Offsetequalsfile_size_bytes. Pass the returnedstorage_pathtoattach_post_media. - Process carousel files in order. Read the post back to verify all attachments and their order. Keep upload tokens private.
Upload and verify
Use prepare_post_media_upload for this draft and local file. Follow its upload_instructions with an HTTP client, then call attach_post_media with the returned storage_path. Read the post back and show the caption, destination, media and import state. Stop before scheduling or publishing.
If an upload is interrupted, use HEAD on the same upload location to recover its offset before resuming. If the grant expires, prepare a new upload. Never attach an incomplete file. Clients with inline MCP app support can also use open_post_media_manager; coding clients do not need that picker.
Schedule or publish after review
Read get_post_context for the relevant caption, media and settings. Confirm the correct account, format, file order and timezone. Media readiness alone does not prove every platform publishing requirement is satisfied; act on validation errors returned by the write tool.
| Your intent | Tool behavior |
|---|---|
| Keep working on the draft | Update its saved content. It remains planning content. |
| Publish at a future time | schedule_post executes directly. Approve the exact date, time and timezone before asking the agent to call it. A scheduled post can publish later without another confirmation. |
| Publish now | publish_post first returns a preview and confirm_token. Approve that preview, then the client repeats the same arguments with the token. |
| Cancel a future publication | Use unschedule_post, then read back its state. |
Confirmation tokens expire after five minutes and bind the action and preview. Changed arguments or a changed target require a fresh preview. Do not reuse approval for a different caption, account or media set.
After scheduling, verify the returned schedule and read it back. After publishing, check the actual publication state and platform link when available. An accepted request or queued job is not proof that the platform has published it.
Recover without creating a second publication
| What happened | Next step |
|---|---|
| A write timed out or its outcome is unclear | Read the current post or conversation before retrying. A completed confirmation can replay its stored result, but an ambiguous provider outcome is not permission to send again. |
| A preview expired or changed | Request a new preview and approve its current contents. |
| A response is too large | Request fewer get_post_context sections or a smaller page; follow the returned cursor or offset for the rest. |
| Access is denied | Verify the selected brand, member area and workspace billing. Reconnect only if authorization needs renewal. |
| The platform rejects the request | Read the reported failure and correct its cause. Keep the same post instead of recreating it automatically. |
Repeating create_post or duplicate_post can create another record. Keep the returned IDs, verify state between steps and use the current tool reference when continuing a workflow.
Now put it to work.
HeyMark learns the rules you just wrote down, then plans, drafts, schedules and replies in that voice. You approve.