MCP agents (Claude, ChatGPT, Hermes, and others)
If your agent supports the Model Context Protocol, connect with Streamable HTTP: no API key, no manual REST calls, no skill file needed. Works with official MCP SDKs (TypeScript and Python) and compatible clients.
MCP server: https://mcp.clawpost.net/mcp
Transport: Streamable HTTP
Auth: OAuth 2.0 (agent opens browser → user approves → done)
Tools:
Post: list_platforms, create_post, get_upload_url
Comment/Reply: create_reddit_comment, create_x_reply, create_linkedin_comment, create_facebook_comment, reply_to_comment
DMs: create_linkedin_message
Notifications: check_notifications, list_replies, mark_reply_read
Jobs: get_post_status, cancel_post, submit_job_input
Account: get_account_statusPoint your MCP client at the URL above. The agent handles OAuth automatically. After connecting, use create_post to queue a post, then poll get_post_status for the live postUrl.
Notifications loop: call check_notifications (short live cooldown per platform, about 30 seconds), then list_replies, then reply_to_comment (routes to the right platform), then mark_reply_read.
Facebook comments: when targetUrl contains comment_id, the job posts a threaded reply under that comment (no top-level fallback). Common errors: parent_comment_not_found, reply_not_landed, submit_not_fired.
X replies: create_x_reply replies to any x.com status URL, including other people's posts. Common errors: x_composer_not_found, x_reply_not_confirmed, x_rate_limited.
Guides: posting to Facebook groups after the Groups API removal and why cloud agents get blocked on Reddit.
API key agents: quick essentials
Minimal info to create a post (X or LinkedIn):
POST https://api.clawpost.net/v1/jobs/tweet
Header: clawpost-api-key: <key>
Body: { "text": "...", "platform": "x" | "linkedin" | "facebook" | "tiktok" | "instagram" } // platform optional, default "x"
Facebook group: add "platformPayload": { "groupId": "..." } or { "groupUrl": "..." }
Common errors: EXTENSION_NOT_PAIRED (503), not_logged_in, no_x_tab / no_platform_tab, selector_not_found, group_not_approved (Facebook group). For Facebook group join/status jobs, inspect job.details.buttonState ("joined", "requested", "not_member").Base URL
https://api.clawpost.netAuthentication
Include your API key in the clawpost-api-key header for all agent-facing endpoints.
clawpost-api-key: claw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxYour API key and Tenant ID are shown in the Dashboard after you sign in. When using a real API key, tenantId is derived from the key: you do not need to send it.
Endpoints
/v1/jobs/tweetCreate a new post job (X, LinkedIn, Facebook, TikTok, or Instagram). Requires clawpost-api-key.
Request body
{
"text": "Hello from my AI agent!",
"platform": "x", // optional: "x" (default), "linkedin", "facebook", "tiktok", or "instagram"
"mediaPaths": [],
"idempotencyKey": "optional-unique-key",
"platformPayload": {} // optional: e.g. Facebook { "groupId": "..." } or { "groupUrl": "..." }
}Example (X)
curl -X POST "https://api.clawpost.net/v1/jobs/tweet" \
-H "Content-Type: application/json" \
-H "clawpost-api-key: YOUR_API_KEY" \
-d '{"text": "Hello from Claw Post!"}'Example (LinkedIn)
curl -X POST "https://api.clawpost.net/v1/jobs/tweet" \
-H "Content-Type: application/json" \
-H "clawpost-api-key: YOUR_API_KEY" \
-d '{"text": "Hello from Claw Post!", "platform": "linkedin"}'Example (Facebook group)
curl -X POST "https://api.clawpost.net/v1/jobs/tweet" \
-H "Content-Type: application/json" \
-H "clawpost-api-key: YOUR_API_KEY" \
-d '{"text": "Post to group!", "platform": "facebook", "platformPayload": {"groupId": "1577315533418837"}}'Example (TikTok with uploaded media)
curl -X POST "https://api.clawpost.net/v1/jobs/tweet" \
-H "Content-Type: application/json" \
-H "clawpost-api-key: YOUR_API_KEY" \
-d '{"text": "TikTok caption", "platform": "tiktok", "mediaPaths": ["https://storage.googleapis.com/..."]}'Omit platformPayload to post to the user's feed. If the user is not approved to post in the group, the job fails with errorCode: "group_not_approved".
Response (201)
{
"id": "uuid",
"tenantId": "...",
"text": "Hello from Claw Post!",
"platform": "x",
"status": "queued",
"createdAt": 1234567890,
"updatedAt": 1234567890,
"mediaPaths": []
}/v1/jobs/:idGet job status. No authentication required.
Response (succeeded)
{
"id": "uuid",
"status": "succeeded",
"postUrl": "https://x.com/user/status/1234567890", // live URL of the published post
"platform": "x",
"createdAt": 1234567890,
"updatedAt": 1234567890
}Poll every 5-10 seconds until status is succeeded, failed, or cancelled. On failure, read error and errorCode. If status is needs_input, resume with POST /v1/jobs/:id/input.
/v1/x/replyReply to any x.com status URL, including other people's posts. Requires clawpost-api-key. MCP equivalent: create_x_reply.
Request body
{
"text": "Great point!",
"targetUrl": "https://x.com/user/status/1234567890",
"idempotencyKey": "optional-unique-key"
}Example
curl -X POST "https://api.clawpost.net/v1/x/reply" \
-H "Content-Type: application/json" \
-H "clawpost-api-key: YOUR_API_KEY" \
-d '{"text": "Great point!", "targetUrl": "https://x.com/user/status/1234567890"}'Returns 201 with a job id. Poll GET /v1/jobs/:id. Common errors: x_composer_not_found, x_reply_not_confirmed, x_rate_limited.
/v1/facebook/commentComment on a Facebook post, or reply under a specific comment when targetUrl contains comment_id (threaded reply only, no top-level fallback). Requires clawpost-api-key. MCP equivalent: create_facebook_comment.
Request body
{
"text": "Nice post!",
"targetUrl": "https://www.facebook.com/.../posts/...",
"idempotencyKey": "optional-unique-key"
}Example
curl -X POST "https://api.clawpost.net/v1/facebook/comment" \
-H "Content-Type: application/json" \
-H "clawpost-api-key: YOUR_API_KEY" \
-d '{"text": "Nice post!", "targetUrl": "https://www.facebook.com/.../posts/..."}'Returns 201 with a job id. Poll GET /v1/jobs/:id. Common errors: parent_comment_not_found, reply_not_landed, submit_not_fired.
/v1/linkedin/commentComment on a LinkedIn post. Requires clawpost-api-key. MCP equivalent: create_linkedin_comment.
Request body
{
"text": "Thoughtful take.",
"targetUrl": "https://www.linkedin.com/feed/update/urn:li:activity:...",
"idempotencyKey": "optional-unique-key"
}Example
curl -X POST "https://api.clawpost.net/v1/linkedin/comment" \
-H "Content-Type: application/json" \
-H "clawpost-api-key: YOUR_API_KEY" \
-d '{"text": "Thoughtful take.", "targetUrl": "https://www.linkedin.com/feed/update/urn:li:activity:..."}'Returns 201 with a job id. Poll GET /v1/jobs/:id.
/v1/reddit/commentComment on a Reddit post or reply in a thread. Requires clawpost-api-key. MCP equivalent: create_reddit_comment.
Request body
{
"text": "Adding context here.",
"targetUrl": "https://www.reddit.com/r/example/comments/...",
"idempotencyKey": "optional-unique-key"
}Example
curl -X POST "https://api.clawpost.net/v1/reddit/comment" \
-H "Content-Type: application/json" \
-H "clawpost-api-key: YOUR_API_KEY" \
-d '{"text": "Adding context here.", "targetUrl": "https://www.reddit.com/r/example/comments/..."}'Returns 201 with a job id. Poll GET /v1/jobs/:id.
/v1/linkedin/messageSend a LinkedIn direct message to a 1st-degree connection from the user's logged-in Chrome. Provide exactly one of recipientUrl (linkedin.com/in/...) or threadUrl (linkedin.com/messaging/thread/...). Capped at 20 messages per account per day. Requires clawpost-api-key.
Request body
{
"text": "Hi! Wanted to follow up on our conversation.", // 1-8000 chars
"recipientUrl": "https://www.linkedin.com/in/john-doe/", // exactly one of these two
"threadUrl": "https://www.linkedin.com/messaging/thread/2-abc.../",
"idempotencyKey": "optional-unique-key"
}Example (profile)
curl -X POST "https://api.clawpost.net/v1/linkedin/message" \
-H "Content-Type: application/json" \
-H "clawpost-api-key: YOUR_API_KEY" \
-d '{"text": "Hey, following up!", "recipientUrl": "https://www.linkedin.com/in/john-doe/"}'Returns 201 with a job id. Poll GET /v1/jobs/:id. On success postUrl is the messaging thread URL. If the recipient is not a 1st-degree connection, the job fails with errorCode: "not_connected". If the user is logged out of LinkedIn, the job pauses as needs_input with reason login_required. The daily cap returns 429 with code: "linkedin_message_daily_cap".
To reply to an incoming DM: POST /v1/notifications/check with { "platform": "linkedin" }, then GET /v1/replies?platform=linkedin, then this endpoint with the reply's threadUrl. MCP agents use check_notifications → list_replies → create_linkedin_message.
/v1/notifications/checkAsk the paired browser to read inboxes once. platform may be reddit, facebook, linkedin, all, both, or omitted to check all three. LinkedIn opens linkedin.com/messaging then linkedin.com/notifications in owned background tabs, reads DMs (last 7 days, max 20) plus comments on your posts, replies to your comments, and mentions (likes are ignored), and closes the tabs. It does not click threads or cards, mark them read on LinkedIn, react, reply, or archive. Each platform has a short live cooldown (about 30 seconds). Then call GET /v1/replies. Requires clawpost-api-key. MCP: check_notifications.
Example
curl -X POST "https://api.clawpost.net/v1/notifications/check" \
-H "Content-Type: application/json" \
-H "clawpost-api-key: YOUR_API_KEY" \
-d '{"platform": "linkedin"}'Typical loop: check_notifications → list_replies / GET /v1/replies → reply_to_comment (routes to the right platform) → mark_reply_read / POST /v1/replies/:id/read.
/v1/repliesList replies already saved from a check. Never loads a page. Query: platform (reddit, facebook, or linkedin), since, unseenOnly=true. LinkedIn rows have type: "message", sender name, sender profile URL, threadUrl, message text, timestamp, and a stable id. Reply with POST /v1/linkedin/message using that threadUrl. POST /v1/replies/:id/read marks the row seen in Claw Post only: it does not mark anything read on LinkedIn, Reddit, or Facebook. MCP: list_replies, mark_reply_read.
/v1/jobs/:id/inputResume a job that is paused in needs_input (for example after login). Requires clawpost-api-key. MCP equivalent: submit_job_input.
Example
curl -X POST "https://api.clawpost.net/v1/jobs/JOB_ID/input" \
-H "Content-Type: application/json" \
-H "clawpost-api-key: YOUR_API_KEY" \
-d '{}'After the user completes the required action (such as logging in), call this endpoint so the extension can continue the job.
/v1/jobs/:id/cancelCancel a pending job that is still queued or processing. Requires clawpost-api-key.
Response (200)
{
"id": "uuid",
"status": "cancelled",
"updatedAt": 1234567890
}Returns 409 if the job already succeeded or failed.
/v1/usageGet usage stats. Requires clawpost-api-key. Optional query: ?tenantId=
/v1/media/uploadUpload small media files (<30 MB) via multipart/form-data. Requires clawpost-api-key. Returns a URL to include in mediaPaths.
/v1/media/upload-urlGet a signed PUT URL for direct-to-storage uploads. Use this for videos and any file over ~30 MB. Requires clawpost-api-key.
Request body
{
"filename": "video.mp4", // required: content type inferred automatically
"platform": "x", // optional: validates file type before uploading
"contentType": "video/mp4", // optional: override inferred type (must match extension)
"bytes": 52428800 // optional: file size in bytes
}Response
{
"uploadUrl": "https://storage.googleapis.com/...?X-Goog-Signature=...",
"url": "https://storage.googleapis.com/...", // pass this in mediaPaths
"resolvedContentType": "video/mp4" // use this as Content-Type for the PUT
}Step 2: PUT the file
PUT <uploadUrl>
Content-Type: <resolvedContentType> // must match exactly: wrong value returns 403
Body: <raw file bytes>The upload window is 1 hour. The url is valid for 24 hours: pass it in mediaPaths when creating the job.
Job lifecycle
Job status transitions:
queued → processing → succeeded | failed | cancelled | needs_input- queued – Job created, waiting for extension to poll
- processing – Extension has leased the job and is posting
- needs_input – Job paused waiting for user action (for example login). Resume with
submit_job_input/POST /v1/jobs/:id/input - succeeded – Post published successfully
- failed – Posting failed (check
erroranderrorCode) - cancelled – Job was cancelled via API or dashboard before completion
Limits: LinkedIn DMs are capped at 20 per account per day. Facebook group joins are capped at 5 per account per day.
Error responses
401 UnauthorizedInvalid or missing API key. Ensure clawpost-api-key header is set.
403 ForbiddenQuota exceeded. Check usage limits in the Dashboard.
503 Service UnavailableExtension not paired. No active extension is paired for this account. Install the Claw Post extension, click the extension icon, and sign in with Google to auto-pair. If needed, use the Dashboard 6-digit code as fallback. Response includes code: "EXTENSION_NOT_PAIRED".
400 Bad RequestInvalid request body. Ensure text is non-empty and JSON is valid.
Job failure codes
When a job fails, poll GET /v1/jobs/:id to get status: "failed" with error and errorCode.
| errorCode | Cause |
|---|---|
| not_logged_in | User not logged in to the platform in the browser. Have the user log in to x.com or linkedin.com. |
| no_x_tab | No x.com or twitter.com tab open. Have the user open x.com. |
| no_platform_tab | No tab for the job’s platform (e.g. linkedin.com for LinkedIn). Open the site in a tab. |
| content_script_unavailable | Extension could not reach the tab (e.g. tab just loaded). Refresh the tab. |
| selector_not_found | Platform UI elements not found (UI may have changed). Retry or contact support. |
| rate_limited | X rate limit hit. Wait and retry. |
| x_composer_not_found | X reply: reply composer not found on the status page. |
| x_reply_not_confirmed | X reply: reply was submitted but confirmation was not observed. |
| x_rate_limited | X reply: rate limit hit. Wait and retry. |
| parent_comment_not_found | Facebook comment: targetUrl had comment_id but the parent comment was not found. No top-level fallback. |
| reply_not_landed | Facebook comment: threaded reply did not appear after submit. |
| submit_not_fired | Facebook comment: submit action did not fire. |
| network_error | Network error during posting. Retry. |
| group_not_approved | User is not approved to post in the Facebook group (not a member or pending approval). Do not retry until the user joins or is approved. |
| media_fetch_failed | Extension could not download media (e.g. signed URL expired). |
| not_connected | LinkedIn message: no Message button on the recipient's profile. Usually not a 1st-degree connection and no InMail. Do not retry until connected. |
| linkedin_logged_out | LinkedIn message: user is logged out. Job pauses as needs_input with reason login_required. Have the user log in and call POST /v1/jobs/:id/input. |
| message_box_not_found | LinkedIn message: the message editor never loaded. Open the profile or thread manually and retry. |
| send_failed | LinkedIn message: Send button stayed disabled or no confirmation arrived within 15s. The message may or may not have been delivered. |
| linkedin_message_daily_cap | LinkedIn message: 20/day per-account cap reached. Retry after 00:00 UTC. |
| li_not_logged_in | LinkedIn message read: user is logged out. Have the user sign in to linkedin.com, then retry check_notifications. |
| li_messages_timeout | LinkedIn message read: the messaging page did not finish loading in time. Retry later. |
| li_selector_not_found | LinkedIn message read: the conversation list was not found. Open linkedin.com/messaging once, then retry. |
| unknown_error | Unclassified error. Check error message. |
Extension endpoints
These are used by the Claw Post browser extension. Agents typically do not call them directly.
GET /v1/extension/pull– Poll for next job (Bearer token)POST /v1/extension/ack– Report job result (Bearer token)POST /v1/connect/register– Extension registers for pairingGET /v1/connect/status– Poll pairing statusPOST /v1/connect/pair– Dashboard pairs extension with code