Hogmatix
In this guide

Developer documentation

The Hogmatix MCP server

Hogmatix runs a remote Model Context Protocol (MCP) server at https://hogmatix.com/mcp. Assistants use it to read your connected X, TikTok and YouTube accounts and your queue, and to schedule or cancel posts for you, after you sign in on hogmatix.com and approve access.

HogmatixUpdated Server version 1.0.1

Summary

Hogmatix is a social media scheduler. Its MCP server lets an assistant act on your Hogmatix account: list your connected X, TikTok and YouTube accounts, show your queue and your posting allowance, upload media, and schedule or cancel posts. You connect an assistant by adding the server URL and approving access on hogmatix.com, so you never give the assistant a password or an API key. A tool call never publishes anything by itself. Each post goes out at the time you chose, at least 10 minutes ahead, and can be canceled until then.

  1. One endpoint for every client. https://hogmatix.com/mcp speaks Streamable HTTP. It accepts POST only, keeps no session, and answers with JSON.
  2. OAuth 2.1 sign-in. The authorization code flow with PKCE (S256) and dynamic client registration. There are two scopes, hogmatix:read and hogmatix:schedule. Access tokens last 1 hour. Refresh tokens last 60 days and rotate on every use.
  3. 16 tools in total. Most clients see 14. Claude on the web, Desktop and mobile sees 11: it gets one-time upload links in place of the import and part-upload tools.
  4. Scheduled, never immediate. The earliest time you can schedule is 10 minutes from now. A published post can't be deleted through the server; delete it on the platform.
  5. X, TikTok and YouTube only. Instagram scheduling, connecting or disconnecting accounts, and billing stay on hogmatix.com.
  6. The free plan works. Any verified, non-disposable email address gets 10 posts in any 30 days. A subscription allows 25 posts in any 24 hours. Videos without sound are refused on every platform.

Quick start

Every client uses the same server URL and the same sign-in. The steps differ only in where you add the URL.

Server URL

https://hogmatix.com/mcp

Before you start

Table 1. Supported clients, how to add Hogmatix, and how each one handles photos and videos.

ClientWhere it worksHow to add itPhotos and videosTools
ChatGPTWeb, desktop and mobile appsInstall from ChatGPT's plugin directoryAttach the file in the chat14
Claudeclaude.ai, Claude Desktop, Claude mobileSettings > ConnectorsA one-time upload link on hogmatix.com11
Claude CodeTerminalclaude mcp addUploads files from your computer14
CodexCodex CLI, Codex IDE extension, ChatGPT desktop appcodex mcp add, then codex mcp loginUploads files from your computer14
Grokgrok.comConnectors > New Connector > CustomText posts only; schedule media on hogmatix.com14
Other MCP clientsAny client with remote MCP and OAuth supportAdd the server URLUploads files if the client can send HTTP PUT requests14

ChatGPT

  1. Open Hogmatix in ChatGPT's plugin directory: chatgpt.com/plugins/plugin_asdk_app_6ac2aaa7dcbc81918086cac62435c144.
  2. Choose Install plugin. ChatGPT sends you to hogmatix.com. Sign in and choose Allow.
  3. Ask, for example: “Show my connected social accounts and upcoming posts.”

To schedule a photo or video, attach it in the chat. Hogmatix copies it into its private storage first, which can take a moment for a large video. If an attachment from a ChatGPT mobile app doesn't come through, attach it again on the web.

Claude on the web, Desktop and mobile

  1. In Claude on the web or in Claude Desktop, open Settings > Connectors.
  2. If Hogmatix is listed in the directory, open it and choose Connect. Otherwise choose Add custom connector, name it Hogmatix and enter https://hogmatix.com/mcp.
  3. Claude sends you to hogmatix.com. Sign in, check that the request returns to claude.ai, and choose Allow.
  4. In a chat, turn Hogmatix on in the tools menu. A connector added on the web or in Claude Desktop is also available in the Claude mobile app.

Claude can't pass files you attach in the chat to Hogmatix. When you ask for a photo or video post, Claude gives you a one-time upload link on hogmatix.com. Open it, choose the file, wait until the page says Uploaded, then tell Claude. The full guide is at hogmatix.com/claude.

Claude Code

Terminal

claude mcp add --transport http hogmatix https://hogmatix.com/mcp

Then run /mcp in Claude Code, choose hogmatix and sign in on hogmatix.com. Claude Code returns to an address on your own computer, so the consent page names “a program on this computer”.

Codex

Terminal

codex mcp add hogmatix --url https://hogmatix.com/mcp
codex mcp login hogmatix

Or add the server to your Codex configuration, then run codex mcp login hogmatix:

~/.codex/config.toml

[mcp_servers.hogmatix]
url = "https://hogmatix.com/mcp"

The Codex CLI, the Codex IDE extension and the ChatGPT desktop app share this configuration.

Grok

  1. Go to grok.com/connectors, choose New Connector, then Custom.
  2. Enter https://hogmatix.com/mcp.
  3. Sign in on hogmatix.com when Grok asks, and choose Allow. Allow pop-ups from grok.com if the sign-in window doesn't open.

From Grok you can schedule text posts on X and manage your queue. To post a photo or video, schedule it on hogmatix.com.

Any other MCP client

Any client that supports remote MCP servers over Streamable HTTP with OAuth can connect. Give it the server URL. It discovers the sign-in endpoints from the server's 401 response (see Authentication). A client that reads an mcpServers configuration can use:

{
  "mcpServers": {
    "hogmatix": {
      "type": "streamable-http",
      "url": "https://hogmatix.com/mcp"
    }
  }
}

The name of the transport field differs between clients (some expect "type": "http"), so check your client's documentation. To post photos or videos, the client must be able to send file bytes with HTTP PUT to a signed URL. A client that can't still schedules text posts on X.

First requests to try

Authentication

hogmatix.com is its own OAuth 2.1 authorization server. Clients sign users in with the authorization code flow and PKCE, and can register themselves with dynamic client registration. Tokens are issued only for the MCP endpoint. OpenID Connect is not supported.

The flow

  1. The client calls POST /mcp without a token and gets 401 with a WWW-Authenticate header that points to the protected resource metadata.
  2. It reads that metadata, which names https://hogmatix.com/ as the authorization server, then reads the authorization server metadata.
  3. If it has no client ID yet, it registers at /register.
  4. It opens /authorize in the browser with a PKCE code challenge.
  5. Hogmatix sends the browser to its consent page. The user signs in if needed, reviews the request and chooses Allow or Cancel.
  6. The browser returns to the client's redirect URI with code, state and iss.
  7. The client exchanges the code and its code verifier at /token for an access token and a refresh token.
  8. It calls /mcp with Authorization: Bearer and the access token, and refreshes the token when it expires.

Response to a request without a token

HTTP/2 401
content-type: application/json; charset=utf-8
www-authenticate: Bearer error="invalid_token", error_description="Missing Authorization header", resource_metadata="https://hogmatix.com/.well-known/oauth-protected-resource/mcp"

{"error":"invalid_token","error_description":"Missing Authorization header"}

Endpoints and discovery

Table 2. OAuth endpoints. All are on https://hogmatix.com.

EndpointPathMethodStandard
Protected resource metadata/.well-known/oauth-protected-resource/mcpGETRFC 9728
Authorization server metadata/.well-known/oauth-authorization-serverGETRFC 8414
Authorization/authorizeGET or POSTOAuth 2.1
Token/tokenPOST, form-encodedOAuth 2.1
Dynamic client registration/registerPOST, JSONRFC 7591
Revocation/revokePOST, form-encodedRFC 7009
Consent page/oauth/consentOpened by /authorizeNone

GET https://hogmatix.com/.well-known/oauth-authorization-server

{
  "issuer": "https://hogmatix.com/",
  "service_documentation": "https://hogmatix.com/",
  "authorization_endpoint": "https://hogmatix.com/authorize",
  "response_types_supported": ["code"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint": "https://hogmatix.com/token",
  "token_endpoint_auth_methods_supported": ["client_secret_post", "none"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "scopes_supported": ["hogmatix:read", "hogmatix:schedule"],
  "revocation_endpoint": "https://hogmatix.com/revoke",
  "revocation_endpoint_auth_methods_supported": ["client_secret_post"],
  "registration_endpoint": "https://hogmatix.com/register"
}

GET https://hogmatix.com/.well-known/oauth-protected-resource/mcp

{
  "resource": "https://hogmatix.com/mcp",
  "authorization_servers": ["https://hogmatix.com/"],
  "scopes_supported": ["hogmatix:read", "hogmatix:schedule"],
  "resource_name": "Hogmatix",
  "resource_documentation": "https://hogmatix.com/"
}

Client registration

Register a public client

POST /register HTTP/1.1
Host: hogmatix.com
Content-Type: application/json

{
  "client_name": "Example MCP client",
  "redirect_uris": ["http://127.0.0.1:8976/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"]
}

Authorization request

Table 3. Parameters accepted by /authorize.

ParameterRequiredValue
response_typeYescode
client_idYesThe ID from registration.
redirect_uriWhen the client registered more than oneOne of the registered URIs.
code_challengeYesThe base64url SHA-256 hash of the code verifier.
code_challenge_methodYesS256. The plain method is refused.
scopeNoSpace-separated. Omit it to get hogmatix:read hogmatix:schedule.
stateNoReturned unchanged. Recommended.
resourceNoIf sent, it must be https://hogmatix.com/mcp (RFC 8707).

Example authorization URL (line breaks added for reading)

https://hogmatix.com/authorize?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A8976%2Fcallback
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
  &scope=hogmatix%3Aread%20hogmatix%3Aschedule
  &state=STATE
  &resource=https%3A%2F%2Fhogmatix.com%2Fmcp

The request waits on the consent page for up to 15 minutes. After that the page shows “This sign-in request has expired” and “Go back to the app you were connecting and start again.”

/authorize sends the browser to https://hogmatix.com/oauth/consent. The page:

Only a person signed in on hogmatix.com can approve a request; a token can't approve another client. Allow returns the browser to the client with code, state and iss=https://hogmatix.com/ (RFC 9207). Cancel returns error=access_denied with error_description=The user declined access.

Scopes

Table 4. Scopes, the exact text the consent page shows for each, and the tools each one unlocks.

ScopeConsent page textTools for most clientsTools for hosted Claude
hogmatix:read “See your connected X, TikTok and YouTube accounts, your scheduled posts and your plan” list_accounts, get_plan, get_tiktok_creator_info, list_scheduled_posts, get_upload_status, get_import_status list_accounts, get_plan, get_tiktok_creator_info, list_scheduled_posts, get_upload_status, get_upload_link_status
hogmatix:schedule “Upload media and schedule or cancel posts on your connected accounts” import_attached_file, create_media_upload, get_upload_part_url, complete_media_upload, schedule_x_post, schedule_tiktok_video, schedule_youtube_video, cancel_scheduled_post get_upload_link_status, create_upload_link, schedule_x_post, schedule_tiktok_video, schedule_youtube_video, cancel_scheduled_post

Tokens

Table 5. What Hogmatix issues and how long each item lasts.

ItemFormatLifetimeNotes
Authorization codeOpaque10 minutesSingle use. Bound to the client, the redirect URI and the PKCE challenge.
Access tokenhgxa_ and 43 characters1 hour (expires_in: 3600)Bearer token for /mcp. Opaque: don't parse it.
Refresh tokenhgxr_ and 43 characters60 days from issueRotates on every use. Each refresh returns a new pair and retires the old refresh token.
Client secretOpaqueDoes not expireConfidential clients only.

Each refresh starts a new 60-day period, so a connection stays active as long as the client refreshes at least once every 60 days. Presenting a refresh token that was already rotated is treated as a stolen token: Hogmatix revokes the whole grant, and the user has to connect again. One exception covers a lost response. Within 120 seconds of a rotation, the previous refresh token is accepted once more, provided the token that replaced it was never used.

Exchange the code

POST /token HTTP/1.1
Host: hogmatix.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTHORIZATION_CODE&code_verifier=CODE_VERIFIER&client_id=CLIENT_ID&redirect_uri=http%3A%2F%2F127.0.0.1%3A8976%2Fcallback&resource=https%3A%2F%2Fhogmatix.com%2Fmcp

Response

{
  "access_token": "hgxa_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "hgxr_…",
  "scope": "hogmatix:read hogmatix:schedule"
}

Refresh

POST /token HTTP/1.1
Host: hogmatix.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=CLIENT_ID

Hogmatix also checks the account on every MCP request. If the account stops qualifying, for example because its email address is no longer verified, requests fail with 403 even while the token is valid.

Revocation

A client revokes access with POST /revoke, sending token (an access or refresh token) and its client credentials. Revoking any token of a grant ends the whole grant: its access tokens, its refresh token and any refresh tokens it already rotated.

As a user, you can end access in three ways:

Rate limits on the OAuth endpoints

Table 6. Requests allowed from one IP address. Over the limit, the endpoint answers 429.

EndpointRequestsWindow
/authorize10015 minutes
/token5015 minutes
/register201 hour
/revoke5015 minutes

Transport and protocol

Table 7. How the server speaks MCP.

ItemValue
EndpointPOST https://hogmatix.com/mcp
TransportStreamable HTTP, stateless. Each request stands alone: there is no Mcp-Session-Id and no session to resume.
Responsesapplication/json. The server never opens an SSE stream. GET, DELETE and every other method answer 405 with Allow: POST.
Request headersAuthorization: Bearer and the access token; Content-Type: application/json; an Accept header that lists both application/json and text/event-stream.
Protocol versions2025-11-25 (latest), 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07. An unsupported MCP-Protocol-Version header gets 400.
Server infoname: "hogmatix", title: "Hogmatix", version: "1.0.1"
Capabilitiestools (with listChanged: true). No resources and no prompts.
InstructionsSent in the initialize result. They tell the model to confirm the account, the exact text or caption, the time and every label with the user before scheduling, and how to upload media in that client. The full text is in the appendix.
Tool annotationsEvery tool sets readOnlyHint, destructiveHint, idempotentHint and openWorldHint explicitly. execution.taskSupport is "forbidden".
NotificationsA POST that carries only notifications or responses gets 202 with no body.

How the tool list is chosen

The server picks a tool list from the redirect URIs the client registered. Claude's hosted apps can't hand a file to a tool or send bytes themselves, so they get upload links instead.

Table 8. Client variants.

Registered redirect URIVariantTools
https://claude.ai/api/mcp/auth_callback or https://claude.com/api/mcp/auth_callbackHosted Claude (web, Desktop, mobile)11
https://chatgpt.com/connector_platform_oauth_redirect or https://chatgpt.com/connector/oauth/…ChatGPT (same tools as default)14
Any other URI, including Claude Code's loopback addressDefault (Claude Code, Codex, Grok, other clients)14

Calls that wait

Some tools wait for work to finish before they answer, so the model doesn't have to poll.

Table 9. Longest wait per tool.

ToolWaits up toWhile
get_import_statusAbout 20 secondsThe import is still downloading or uploading
get_upload_link_statusAbout 20 secondsThe user hasn't finished uploading
import_attached_fileAbout 40 secondsThe attachment is copied into storage
complete_media_uploadAbout 60 secondsThe upload is verified and made ready

Each tool call has a 90-second limit inside Hogmatix. Set your client's tool-call timeout to at least 90 seconds.

Example requests

initialize

curl https://hogmatix.com/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"example","version":"1.0.0"}}}'

Response (instructions shortened)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": { "tools": { "listChanged": true } },
    "serverInfo": { "name": "hogmatix", "title": "Hogmatix", "version": "1.0.1" },
    "instructions": "Hogmatix schedules posts to the user's connected X, TikTok and YouTube accounts. …"
  }
}

tools/call

curl https://hogmatix.com/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_accounts","arguments":{"platform":"x"}}}'

Response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "{\n  \"x\": [\n    {\n      \"profile\": \"yourhandle\",\n      \"screenName\": \"YourHandle\"\n    }\n  ]\n}" }
    ]
  }
}

Platforms and capabilities

The server schedules to X, TikTok and YouTube. Instagram is supported on hogmatix.com but not through the MCP server.

Table 10. What an assistant can do on each platform through the MCP server.

CapabilityXTikTokYouTubeInstagram
List connected accountsYesYesYesNo
List scheduled and recent postsYes, per accountYesYesNo
Post immediatelyNoNoNoNo
Schedule (10 minutes or more ahead)YesYesYesNo (hogmatix.com only)
Text-only postsYesNoNoNo
ImagesJPEG, PNG, WebP, GIFNoNoNo
VideoMP4, MOVMP4, MOV, WebMMP4, MOV, WebMNo
Media per postOne fileOne videoOne videoNo
ThreadsYesNoNoNo
Long postsYesNoNoNo
Live account settingsNoYes (get_tiktok_creator_info)NoNo
Cancel before publishingYesYesYesNo
Delete after publishingNoNoNoNo
AnalyticsNoNoNoNo

Tool reference

The server has 16 tools. Most clients see 14 of them; hosted Claude sees 11. The table lists every tool, the scope it needs, which clients see it, and its annotations. Exact JSON schemas are in the appendix.

Table 11. All tools. “Default” covers ChatGPT, Claude Code, Codex, Grok and other clients.

ToolScopeDefaultHosted ClaudereadOnlydestructiveidempotentopenWorld
Accounts, plan and queue
list_accountsreadYesYestruefalsetruefalse
get_planreadYesYestruefalsetruefalse
get_tiktok_creator_inforeadYesYestruefalsetruetrue
list_scheduled_postsreadYesYestruefalsetruefalse
Media
get_upload_statusreadYesYestruefalsetruefalse
import_attached_filescheduleYesNofalsefalsefalsefalse
get_import_statusreadYesNotruefalsetruefalse
create_media_uploadscheduleYesNofalsefalsefalsefalse
get_upload_part_urlscheduleYesNofalsefalsefalsefalse
complete_media_uploadscheduleYesNofalsefalsefalsefalse
create_upload_linkscheduleNoYesfalsefalsefalsefalse
get_upload_link_statusread or scheduleNoYestruefalsetruefalse
Scheduling and canceling
schedule_x_postscheduleYesYesfalsetruefalsetrue
schedule_tiktok_videoscheduleYesYesfalsetruefalsetrue
schedule_youtube_videoscheduleYesYesfalsetruefalsetrue
cancel_scheduled_postscheduleYesYesfalsetruetruefalse

Conventions

Typical sequences

  1. Text post on X. list_accounts, then schedule_x_post.
  2. Photo or video in ChatGPT. list_accounts, then import_attached_file for one platform (and get_import_status if it isn't ready yet), then that platform's schedule tool. Repeat per platform.
  3. Photo or video in hosted Claude. create_upload_link, the user uploads the file on the link's page, then get_upload_link_status until state is ready, then the schedule tool with the returned uploadId.
  4. Photo or video from a client that can send bytes (Claude Code, Codex). create_media_upload, then for each part get_upload_part_url and an HTTP PUT, then complete_media_upload, then the schedule tool.
  5. TikTok. Call get_tiktok_creator_info first, let the user choose from its options, show them the required summary and declaration, and get their explicit go-ahead before schedule_tiktok_video.

Accounts, plan and queue

list_accountsreadall clients List the X, TikTok and YouTube accounts connected to the user's Hogmatix account.

Returns the accounts the user connected on hogmatix.com. Call it first: the scheduling tools need an account's profile (X), openId (TikTok) or channelId (YouTube).

Parameters

NameTypeRequiredNotes
platformstringNoOne of x, tiktok, youtube. Lists only that platform. Omit to list all three.

Returns

An object with one key per platform requested. The X profile is the lowercase handle Hogmatix uses as the account key. needsReauth: true means the account must be connected again on hogmatix.com before it can post.

{
  "x": [{ "profile": "yourhandle", "screenName": "YourHandle" }],
  "tiktok": [{ "openId": "example-open-id", "username": "yourname", "displayName": "Your Name", "needsReauth": false }],
  "youtube": [{ "channelId": "UCexample", "title": "Your Channel", "needsReauth": false }]
}

Errors

Only the general errors in Errors.

Example call

{ "name": "list_accounts", "arguments": { "platform": "tiktok" } }
get_planreadall clients Show the user's plan and how much of the posting allowance is used.

Reports the plan and the posting allowance. It does not offer subscriptions or change billing, and it does not report the usage allowance for X posting.

Parameters

None.

Returns

FieldMeaning
planpremium (a subscription, including a trial) or free.
usage.usedPosts published in the current window.
usage.limitPosts allowed in the window: 25 for premium, 10 for free.
usage.windowHoursLength of the rolling window: 24 for premium, 720 (30 days) for free.
usage.resetsAtWhen the limit is reached, the time the next post becomes possible. Otherwise null.
usage.enforcedtrue when posts over the limit are held back.
{
  "plan": "free",
  "usage": { "used": 3, "limit": 10, "windowHours": 720, "resetsAt": null, "enforced": true }
}

Errors

Only the general errors in Errors.

Example call

{ "name": "get_plan", "arguments": {} }
get_tiktok_creator_inforeadall clients Read a TikTok account's current posting options live from TikTok.

Reads the account's creator settings from TikTok at call time: who it posts as, the privacy levels it may use, its longest allowed video, and the interactions the creator turned off. It also returns the declaration TikTok requires the creator to see before posting. Call it before schedule_tiktok_video and let the user choose from these options.

Parameters

NameTypeRequiredNotes
openIdstringYesThe TikTok account's openId from list_accounts. At least 1 character.

Returns

TikTok's fields creator_nickname, creator_username, privacy_level_options, comment_disabled, duet_disabled, stitch_disabled and max_video_post_duration_sec, plus postingAs, declaration and brandedContentDeclaration. When TikTok says the account can't post right now, the result has blocked: true with blockCode and blockReason, and no declaration; don't schedule.

{
  "creator_nickname": "Your Name",
  "creator_username": "yourname",
  "privacy_level_options": ["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "SELF_ONLY"],
  "comment_disabled": false,
  "duet_disabled": false,
  "stitch_disabled": true,
  "max_video_post_duration_sec": 600,
  "postingAs": "Your Name (@yourname)",
  "declaration": "By posting, you agree to TikTok's Music Usage Confirmation.",
  "brandedContentDeclaration": "By posting, you agree to TikTok's Branded Content Policy and Music Usage Confirmation."
}

Errors

  • “Reconnect TikTok before refreshing creator information.” The account must be connected again on hogmatix.com.

Example call

{ "name": "get_tiktok_creator_info", "arguments": { "openId": "example-open-id" } }
list_scheduled_postsreadall clients List scheduled and recent posts for one platform, with their status.

Lists the user's posts on one platform. Pending posts come first, soonest first; finished posts follow, newest first.

Parameters

NameTypeRequiredNotes
platformstringYesOne of x, tiktok, youtube.
profilestringFor XX only: the profile from list_accounts.

Returns

{ "posts": [ … ] }. Each post has its id, scheduledAt, status and error, plus the platform's own fields: the text and format on X; the caption, privacy and disclosure choices on TikTok; the title, description and privacy on YouTube.

PlatformStatus values
Xpending, posting, posted, failed. A post with media can also show the state of its upload, such as cancelled or failed-safe.
TikTokpending, uploading, uploaded, cancelled, failed, or unknown: TikTok may have received the post, so check the profile before posting it again.
YouTubepending, uploading, uploaded, or the state of its upload, such as cancelled or failed-safe.

Finished X text posts leave the list 7 days after they go out. Posts made from an upload stay listed for at least 90 days.

{
  "posts": [
    {
      "id": "sp_1763650800000_k3j9x",
      "profile": "yourhandle",
      "text": "Our new release is out today.",
      "format": "shortform",
      "scheduledAt": "2026-11-20T17:00:00.000Z",
      "status": "pending",
      "postedAt": null,
      "tweetId": null,
      "error": null,
      "hasMedia": false
    }
  ]
}

Errors

  • “profile is required for X.”

Example call

{ "name": "list_scheduled_posts", "arguments": { "platform": "x", "profile": "yourhandle" } }

Media

Media goes into Hogmatix's private storage before it is scheduled. There are three ways in, depending on the client. Each upload or import holds one of the account's 5 upload slots until it is scheduled.

get_upload_statusreadall clients Check a media upload's state. It is ready to schedule once the state is promoted.

Returns the upload record. state is promoted when the file is ready to schedule. Other states show progress (initiated, uploading, sealing, promoting) or an end (failed, aborted, expired); diagnostic explains a failure. For a video, audio reports the sound check (see Sound check).

Parameters

NameTypeRequiredNotes
uploadIdstringYesPattern ^upl_[A-Za-z0-9_-]{1,128}$.

Returns

{
  "uploadId": "upl_example123",
  "purpose": "tiktok-video",
  "displayFilename": "launch.mp4",
  "mimeType": "video/mp4",
  "byteSize": 48211234,
  "partSize": 16777216,
  "partCount": 3,
  "state": "promoted",
  "createdAt": "2026-11-12T17:02:11.000Z",
  "activityAt": "2026-11-12T17:03:40.000Z",
  "promotedAt": "2026-11-12T17:03:40.000Z",
  "expiresAt": "2026-11-19T17:02:11.000Z",
  "diagnostic": null,
  "audio": { "checked": true, "present": true, "meanDb": -21.4, "verdict": "ok" }
}

The audio object is shortened here. It also carries the peak level, sample rate, channels, codec and track count.

Errors

Only the general errors in Errors.

Example call

{ "name": "get_upload_status", "arguments": { "uploadId": "upl_example123" } }
import_attached_filewritesexcept hosted Claude Copy a file the user attached in a ChatGPT chat into Hogmatix's storage, for one platform.

ChatGPT fills in file with a signed link to the attachment (the tool declares it as a file parameter). Hogmatix downloads the file from ChatGPT's file hosts only, checks it against the platform's media rules, and stores it. The tool waits up to about 40 seconds. When state is ready, pass uploadId to the platform's schedule tool. If it is still downloading or uploading, call get_import_status.

Each platform needs its own import, so import for one platform, schedule that post, then import for the next. Calling again with the same attachment and purpose returns the same import until its upload has been scheduled. When the account's upload slots are full, the import fails and asks the user to schedule pending files first; it never deletes other files to make room. The tool is listed for every non-Claude client but works only in ChatGPT, because only ChatGPT's file hosts are accepted.

Parameters

NameTypeRequiredNotes
fileobjectYesThe attachment. ChatGPT fills this in.
file.download_urlstringYesChatGPT's signed link. Only links on oaiusercontent.com and chatgpt.com are accepted.
file.file_idstringYesChatGPT's file ID.
file.mime_typestringNoThe file's media type.
file.file_namestringNoThe file's name.
purposestringYesOne of x-media, tiktok-video, youtube-video.

Returns

The import. durationSec is a video's length in seconds, needed by schedule_tiktok_video; if it is null, ask the user. A failed import comes back as a tool error with error explaining why.

{
  "importId": "imp_example123",
  "state": "ready",
  "filename": "launch.mp4",
  "mimeType": "video/mp4",
  "byteSize": 48211234,
  "durationSec": 41.2,
  "uploadId": "upl_example123"
}

Errors

  • “The file argument was missing from this call. …” Call again with the attachment; if it is missing again, ask the user to attach the file again.
  • “The attached file arrived as a placeholder, not a file. …” or “… arrived without its download link.” Attach the file again in ChatGPT on the web, or upload it on hogmatix.com.
  • “That link is not from ChatGPT's file storage, so Hogmatix can't import it. …”
  • “The attachment link has expired. Attach the file again.”
  • Upload quota and media type errors (see Tool errors).

Example call

{
  "name": "import_attached_file",
  "arguments": {
    "file": {
      "download_url": "https://files.oaiusercontent.com/example",
      "file_id": "file-example",
      "mime_type": "video/mp4",
      "file_name": "launch.mp4"
    },
    "purpose": "tiktok-video"
  }
}
get_import_statusreadexcept hosted Claude Check an import started by import_attached_file.

Waits up to about 20 seconds while the import is still downloading or uploading. When state is ready, schedule with uploadId. A failed import comes back as a tool error and says why in error.

Parameters

NameTypeRequiredNotes
importIdstringYesPattern ^imp_[A-Za-z0-9_-]{1,128}$.

Returns

The same shape as import_attached_file: importId, state, filename, mimeType, byteSize, durationSec, and uploadId or error when present.

Errors

  • “Hogmatix no longer has this import: it expired or the server restarted. Call import_attached_file again with the same attachment.”

Example call

{ "name": "get_import_status", "arguments": { "importId": "imp_example123" } }
create_media_uploadwritesexcept hosted Claude Start a direct upload from a client that can send file bytes itself.

Starts an upload into private storage and returns the upload record with uploadId, partSize and partCount. Parts are 16 MiB (16,777,216 bytes) except the last, and are numbered from 1. For each part, call get_upload_part_url, then PUT the bytes. Finish with complete_media_upload. For a file attached in ChatGPT, use import_attached_file instead.

An unfinished upload expires after about 2 hours without activity. A finished upload that is never scheduled is cleared about a day later.

Parameters

NameTypeRequiredNotes
purposestringYesOne of x-media, tiktok-video, youtube-video.
filenamestringYes1 to 200 characters.
mimeTypestringYes3 to 100 characters, such as video/mp4, video/quicktime or image/png. Must be allowed for the purpose (see Media types and sizes).
byteSizeintegerYesGreater than 0, and within the size limit for the type.

Returns

The upload record, as in get_upload_status, with state initiated.

Errors

  • “Too many active uploads. Finish or cancel one before starting another.”
  • “Your active upload byte limit would be exceeded.”, “Your daily upload count limit has been reached.” or “Your daily upload byte limit would be exceeded.”
  • “Upload capacity is temporarily full. Try again later.”

Example call

{
  "name": "create_media_upload",
  "arguments": {
    "purpose": "youtube-video",
    "filename": "launch.mp4",
    "mimeType": "video/mp4",
    "byteSize": 48211234
  }
}
get_upload_part_urlwritesexcept hosted Claude Register one part of an upload and get a short-lived signed URL to PUT it to.

Records the part's SHA-256 checksum on the upload and returns a signed URL that lives about 15 minutes. PUT exactly expectedSize bytes to url, with every header in headers. If a PUT fails, call again with the same checksum for a fresh URL. A different checksum for the same part is refused. Each call counts toward the upload's limit of 128 part URLs.

Parameters

NameTypeRequiredNotes
uploadIdstringYesPattern ^upl_[A-Za-z0-9_-]{1,128}$.
partNumberintegerYes1 or more, up to the upload's partCount.
checksumSha256stringYesThe base64 SHA-256 digest of the part's bytes (44 characters). The schema allows 40 to 64.

Returns

{
  "partNumber": 1,
  "expectedSize": 16777216,
  "expiresAt": "2026-11-12T17:17:11.000Z",
  "url": "https://signed-upload-url.example",
  "headers": { "x-amz-checksum-sha256": "BASE64_SHA256_OF_THE_PART" }
}

Compute the checksum and send a part

openssl dgst -sha256 -binary part1.bin | base64
curl -X PUT "$PART_URL" \
  -H "x-amz-checksum-sha256: $CHECKSUM" \
  --data-binary @part1.bin

Errors

  • “A retry for this part must use the same deterministic byte range.” The part was registered before with a different checksum.
  • “checksumSha256 must be a base64-encoded SHA-256 digest.”

Example call

{
  "name": "get_upload_part_url",
  "arguments": {
    "uploadId": "upl_example123",
    "partNumber": 1,
    "checksumSha256": "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg="
  }
}
complete_media_uploadwritesexcept hosted Claude Finish an upload after every part was sent, and wait for it to be ready.

Verifies every part and the file type, and waits up to about a minute for the upload to reach promoted. If a part's size or checksum, or the file's type, fails verification, the upload is marked failed and must be started again. If parts are missing, PUT them and call this again. A video's sound is measured at this step.

Parameters

NameTypeRequiredNotes
uploadIdstringYesPattern ^upl_[A-Za-z0-9_-]{1,128}$.

Returns

{ "uploadId": "upl_example123", "state": "promoted" }

If the upload is still finishing after a minute:

{ "uploadId": "upl_example123", "state": "promoting", "note": "Still finalizing; check get_upload_status before scheduling." }

Errors

  • “Upload stopped in state failed: …” (or aborted, expired, repair), followed by the diagnostic.
  • “The uploaded bytes do not match the declared media type …”

Example call

{ "name": "complete_media_upload", "arguments": { "uploadId": "upl_example123" } }
create_upload_linkwriteshosted Claude only Create a one-time link to a hogmatix.com page where the user uploads a file for one platform.

Hosted Claude can't pass chat attachments to a tool, so it gives the user a link instead. The user opens url in a browser, chooses a photo or video, and the page uploads it to Hogmatix's private storage. The link takes one file. It expires after 30 minutes if unused; once an upload starts, it has 2 hours to finish. An account can have 5 unused links at once. accepts lists the file types and sizes the purpose takes.

Parameters

NameTypeRequiredNotes
purposestringYesOne of x-media, tiktok-video, youtube-video.

Returns

{
  "linkId": "lnk_AbCdEfGhIjKlMnOpQrStUv",
  "purpose": "tiktok-video",
  "platform": "TikTok",
  "url": "https://hogmatix.com/upload#hgxl_…",
  "expiresAt": "2026-11-12T17:32:00.000Z",
  "accepts": [
    { "mimeType": "video/mp4", "maxBytes": 536870912, "maxLabel": "512 MiB" },
    { "mimeType": "video/quicktime", "maxBytes": 536870912, "maxLabel": "512 MiB" },
    { "mimeType": "video/webm", "maxBytes": 536870912, "maxLabel": "512 MiB" }
  ]
}

The link's secret is in the URL fragment (after #), which browsers never send to a server.

Errors

  • “This account already has 5 unused upload links. Use one, or wait up to 30 minutes for them to expire.”

Example call

{ "name": "create_upload_link", "arguments": { "purpose": "tiktok-video" } }
get_upload_link_statusreadhosted Claude only Check an upload link and get the uploadId once the file is ready.

Waits up to about 20 seconds while the user hasn't finished uploading. Listed for a grant with either scope, so a grant that can create links can always learn the uploadId they produce.

stateMeaning
waitingThe page wasn't opened, or no file was chosen yet.
uploadingThe file is on its way.
readySchedule with uploadId.
failederror says why. Create a new link.
expiredThe link wasn't used within 30 minutes.

Parameters

NameTypeRequiredNotes
linkIdstringYesPattern ^lnk_[A-Za-z0-9_-]{22}$.

Returns

When ready, durationSec is a video's length in seconds for schedule_tiktok_video. It is null when the browser couldn't read it; then ask the user. For a video, audio reports the sound check.

{
  "linkId": "lnk_AbCdEfGhIjKlMnOpQrStUv",
  "purpose": "tiktok-video",
  "state": "ready",
  "expiresAt": "2026-11-12T17:32:00.000Z",
  "uploadId": "upl_example123",
  "filename": "launch.mp4",
  "mimeType": "video/mp4",
  "byteSize": 48211234,
  "durationSec": 41.2,
  "audio": { "checked": true, "present": true, "meanDb": -21.4, "verdict": "ok" }
}

Errors

  • “Hogmatix has no such upload link for this account. Create a new one with create_upload_link.”

Example call

{ "name": "get_upload_link_status", "arguments": { "linkId": "lnk_AbCdEfGhIjKlMnOpQrStUv" } }

Scheduling and canceling

These tools change what will appear publicly, so they are marked destructive. Nothing is published when they run: the post goes out at scheduledAt.

schedule_x_postwritesall clients Schedule a post, thread or long post on a connected X account.

At the scheduled time Hogmatix publishes the post on X, where it is public. Hogmatix never deletes published posts from X; until publishing, cancel_scheduled_post can cancel it. For a thread, separate the posts with a blank line. Optionally attach one file uploaded with purpose x-media. Confirm the account, the exact text and the time with the user first.

Retrying is safe. The same account, text, format, time and upload always produce the same request, so a retry after a lost response returns the post already queued instead of a second post.

Parameters

NameTypeRequiredNotes
profilestringYesThe X profile from list_accounts. At least 1 character.
textstringYes1 to 25,000 characters. For a thread, separate the posts with a blank line.
formatstringNoOne of shortform, thread, longform. Default shortform. See X rules.
scheduledAtstringYesISO 8601 with a time-zone offset, at least 10 minutes ahead.
uploadIdstringNoA ready upload with purpose x-media. Pattern ^upl_[A-Za-z0-9_-]{1,128}$.

Returns

id starts with sp_ for a text post and sub_ for a post with media. costNote appears only when the text contains a link, and says what X posting will do with it.

{
  "scheduled": true,
  "id": "sp_1763650800000_k3j9x",
  "scheduledAt": "2026-11-20T17:00:00.000Z",
  "profile": "yourhandle",
  "format": "shortform",
  "costNote": "Contains a link: links are removed before posting to X."
}

Errors

  • The three scheduledAt errors (see Tool errors).
  • “Long posts with links can't be sent to X. Remove the link and try again.”
  • A usage allowance message, such as “The free plan's monthly usage allowance is used up. More becomes available on 2026-12-01.”
  • For media: the upload, sound check and claim errors in Tool errors.

Example call

{
  "name": "schedule_x_post",
  "arguments": {
    "profile": "yourhandle",
    "text": "Our new release is out today.",
    "format": "shortform",
    "scheduledAt": "2026-11-20T09:00:00-08:00"
  }
}
schedule_tiktok_videowritesall clients Schedule an uploaded video on a connected TikTok account, with every Direct Post choice explicit.

At the scheduled time Hogmatix publishes the video on TikTok. Hogmatix can't remove a published video; until publishing, cancel_scheduled_post can cancel it. Every choice is explicit, as TikTok's Direct Post rules require. Hogmatix checks the creator's settings and its posting-density rules when you schedule, and checks the settings again before publishing.

Before calling, show the user: “Posting as” with postingAs from get_tiktok_creator_info; the caption and time; the chosen privacy option; the comment, Duet and Stitch settings; the disclosure and AI-generated choices; and the declaration “By posting, you agree to TikTok's Music Usage Confirmation.” (with branded content: “By posting, you agree to TikTok's Branded Content Policy and Music Usage Confirmation.”). Then get the user's explicit go-ahead, even when the request already states every choice.

Parameters

All parameters are required.

NameTypeRequiredNotes
openIdstringYesThe TikTok account's openId from list_accounts.
uploadIdstringYesA ready upload with purpose tiktok-video.
captionstringYesUp to 2,200 characters. May be empty.
scheduledAtstringYesISO 8601 with a time-zone offset, at least 10 minutes ahead.
privacyLevelstringYesOne of PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY, and it must be in the account's privacy_level_options.
aiGeneratedbooleanYesWhether TikTok shows its AI-generated label on the video. Required by TikTok.
yourBrandbooleanYesCommercial disclosure: the video promotes the creator's own business. Required when the caption mentions the account's own handle.
brandedContentbooleanYesCommercial disclosure: paid promotion of a third party. Only with PUBLIC_TO_EVERYONE or MUTUAL_FOLLOW_FRIENDS.
allowCommentsbooleanYesStays off if the creator disabled comments.
allowDuetbooleanYesStays off if the creator disabled Duet.
allowStitchbooleanYesStays off if the creator disabled Stitch.
durationSecnumberYesThe video's length in seconds, greater than 0. import_attached_file and get_upload_link_status return it. Rounded up, it must not exceed max_video_post_duration_sec.

Returns

{
  "scheduled": true,
  "id": "sub_example123",
  "state": "scheduled",
  "scheduledAt": "2026-11-21T02:00:00.000Z"
}

Errors

  • “Branded content can't be private: choose PUBLIC_TO_EVERYONE or MUTUAL_FOLLOW_FRIENDS.”
  • “That privacy setting is no longer available for this TikTok account. Choose one of the current options.”
  • “TikTok allows up to 600s for this account; this video is 720s.” (with the account's numbers)
  • “This caption mentions @yourname. Turn on Disclose video content and choose Your brand.” Set yourBrand to true.
  • “This account already has a TikTok post within 2 hours of that time. Pick a later time.”
  • “This would put 4 TikTok posts for this account inside one 24-hour window. The limit is 3. Pick a later time. Posts made in the TikTok app are not counted.”
  • “TikTok needs this account connected again before it can post. Reconnect to re-authorize.”
  • The scheduledAt, upload, sound check and claim errors in Tool errors.

Example call

{
  "name": "schedule_tiktok_video",
  "arguments": {
    "openId": "example-open-id",
    "uploadId": "upl_example123",
    "caption": "Behind the scenes of our launch",
    "scheduledAt": "2026-11-20T18:00:00-08:00",
    "privacyLevel": "SELF_ONLY",
    "aiGenerated": false,
    "yourBrand": false,
    "brandedContent": false,
    "allowComments": true,
    "allowDuet": false,
    "allowStitch": false,
    "durationSec": 41.2
  }
}
schedule_youtube_videowritesall clients Schedule an uploaded video on a connected YouTube channel.

At the scheduled time Hogmatix uploads the video to YouTube with the privacy you chose. Hogmatix can't remove an uploaded video; until then, cancel_scheduled_post can cancel it. Confirm the channel, the title, the privacy and the time with the user first. Videos are uploaded in YouTube category 22 (People & Blogs) with no tags.

Parameters

NameTypeRequiredNotes
channelIdstringYesThe channel's channelId from list_accounts.
uploadIdstringYesA ready upload with purpose youtube-video.
titlestringYes1 to 100 characters.
descriptionstringNoUp to 5,000 characters. Default empty.
privacyStatusstringYesOne of private, unlisted, public.
madeForKidsbooleanYesYouTube's made-for-kids declaration.
scheduledAtstringYesISO 8601 with a time-zone offset, at least 10 minutes ahead.

Returns

{
  "scheduled": true,
  "id": "sub_example456",
  "state": "scheduled",
  "scheduledAt": "2026-11-21T20:00:00.000Z"
}

Errors

  • The scheduledAt, upload, sound check and claim errors in Tool errors.

Example call

{
  "name": "schedule_youtube_video",
  "arguments": {
    "channelId": "UCexample",
    "uploadId": "upl_example456",
    "title": "Behind the scenes",
    "description": "How we built this release.",
    "privacyStatus": "unlisted",
    "madeForKids": false,
    "scheduledAt": "2026-11-21T12:00:00-08:00"
  }
}
cancel_scheduled_postwritesall clients Cancel a post that has not been published yet.

Canceling is permanent. The post can't be restored, and posting it later means scheduling a new post, with its media imported or uploaded again. Posts already on X, TikTok or YouTube can't be recalled here.

Parameters

NameTypeRequiredNotes
platformstringYesOne of x, tiktok, youtube.
idstringYesThe id from list_scheduled_posts or the schedule result. Pattern ^[A-Za-z0-9_-]{1,128}$. TikTok and YouTube IDs start with sub_.

Returns

{ "cancelled": true, "platform": "x", "id": "sp_1763650800000_k3j9x" }

Errors

  • “Only pending posts can be cancelled.” An X text post that is already posting, posted or failed.
  • “Only a submission that has not started provider work can be cancelled.” A post made from an upload that is already going out or finished.
  • “Scheduled post not found.” or “Submission not found.” The ID doesn't belong to this account.

Example call

{ "name": "cancel_scheduled_post", "arguments": { "platform": "x", "id": "sp_1763650800000_k3j9x" } }

Limits and rules

These limits apply to every client. They are the same limits Hogmatix applies on hogmatix.com, because every tool works through Hogmatix's own API with the user's token.

Plans and posting allowance

Table 12. Plans and how many posts each allows. Counts cover all platforms together.

PlanWho gets itPostsRolling window
FreeAny account with a verified email address that isn't a disposable address1030 days
TrialFirst-time subscribers, for seven days2524 hours
Subscription (US$20 a month)Subscribers2524 hours

Usage allowance for X posting

Posting to X uses X's paid API, so X posts draw on a monthly usage allowance. TikTok and YouTube scheduling do not.

Each plan includes an allowance that covers ordinary scheduling; a larger plan includes more. Every part of a thread counts as one post. Links are removed from X posts before posting, so a post never counts at X's higher rate for links.

Scheduling

Table 13. Timing rules.

RuleValue
Earliest time10 minutes from now
Time formatISO 8601 with seconds optional and a time-zone offset or Z: YYYY-MM-DDTHH:MM[:SS[.fff]](Z|±HH:MM)
Post immediatelyNot available through the MCP server
TikTok post that starts lateNot posted if more than 6 hours late. Schedule it again.
X text posts in the listKept 7 days after they finish
Posts from uploads in the listKept at least 90 days after they finish

Media types and sizes

Table 14. Accepted types and maximum sizes per upload purpose. 1 MiB is 1,048,576 bytes.

PurposePlatformTypeMedia typeMaximum
x-mediaXJPEGimage/jpeg5 MiB
PNGimage/png5 MiB
WebPimage/webp5 MiB
GIFimage/gif15 MiB
MP4video/mp4512 MiB
MOVvideo/quicktime512 MiB
tiktok-videoTikTokMP4video/mp4512 MiB
MOVvideo/quicktime512 MiB
WebMvideo/webm512 MiB
youtube-videoYouTubeMP4video/mp4512 MiB
MOVvideo/quicktime512 MiB
WebMvideo/webm512 MiB

The file's bytes must match its declared type. Otherwise the upload fails with “The uploaded bytes do not match the declared media type …”.

Upload quotas

Table 15. Per-account limits on uploads and imports.

LimitValue
Active upload slots5 per account. An upload or import holds a slot from the moment it starts until it is scheduled.
Bytes in active uploads1 GiB per account
New uploads20 per rolling 24 hours, and 2 GiB per rolling 24 hours
Part size16 MiB (the last part may be smaller)
Part URLs128 per upload; each lives about 15 minutes
Finishing attempts10 per upload
Unfinished uploadExpires after about 2 hours without activity
Finished upload never scheduledCleared about a day later

Table 16. Limits on links from create_upload_link.

LimitValue
Time to open and start30 minutes
Time to finish after starting2 hours
Files per link1
Unused links per account5

Chat imports (ChatGPT)

Table 17. Limits on import_attached_file.

LimitValue
Accepted hostsoaiusercontent.com, chatgpt.com
Imports running at once2 per account
Imports per day20 per account, and 2 GiB per account
Download deadline10 minutes
Storing deadline30 minutes
Import statusKept about a day. A server restart loses it; import the attachment again.

X rules

Table 18. What happens to each X format at publishing time.

FormatHow it postsLinksMedia
shortformOne post. Line breaks and repeated spaces become single spaces, em and en dashes become hyphens, and a quote mark at the very start or end is removed.Removed before posting. A bare domain keeps its name: “OpenAI.com” becomes “OpenAI”.One file
threadSplit on blank lines; each part replies to the one before.A part that contains a link is skipped.On the first part only
longformOne long post with its line breaks kept.Refused when you schedule: “Long posts with links can't be sent to X. Remove the link and try again.”One file

TikTok rules

YouTube rules

Sound check: videos without sound are refused

Hogmatix doesn't post videos without sound, on any platform. A video with no audio track, or one whose mean volume is below -50 dB, is refused. So is a video the check couldn't measure. There is no override through the MCP server. Photos are never checked.

Each video is measured when its upload finishes, again when it is scheduled, and again right before publishing. get_upload_status and get_upload_link_status show the result in audio.verdict, so the model can warn the user before scheduling.

Table 19. Sound check verdicts.

audio.verdictMeaningResult
okThe video has sound at a normal level.Can be scheduled
no-soundNo audio track.Refused. Add a soundtrack and upload again.
silentMean volume below -50 dB.Refused. Fix the audio and upload again.
check-failedThe check couldn't run.Refused until the check works. Try again shortly.
not-checkedNot measured yet.Measured when the post is scheduled

Canceling and deleting

Errors

Errors arrive at three levels: HTTP responses from /mcp (before any tool runs), OAuth errors during sign-in, and tool errors (isError: true) from a tool call.

HTTP and JSON-RPC errors from /mcp

Table 20. Responses from the endpoint itself.

HTTPCodeMessageWhat to do
401invalid_token“Missing Authorization header”, “Invalid access token.” or “Invalid or expired access token.”Refresh the token, or sign in again.
403-32001“Your Hogmatix account is not active.”Verify your email address on hogmatix.com with a non-disposable address, or subscribe, then connect again.
503-32002“Hogmatix could not check your account right now.”Try again in a moment.
405-32000“Method not allowed.”Use POST.
406-32000“Not Acceptable: Client must accept both application/json and text/event-stream”Send Accept: application/json, text/event-stream.
415-32000“Unsupported Media Type: Content-Type must be application/json”Send Content-Type: application/json.
400-32000“Bad Request: Unsupported protocol version: …”Use a supported protocol version.
500-32603“Internal server error”Try again. If it persists, contact support.

OAuth errors

Table 21. Errors during registration, authorization and token requests.

CodeMessageCause
invalid_client_metadata“redirect_uris must be https URLs or http loopback URLs.”A redirect URI that isn't https or a loopback http address.
invalid_client_metadata“Only the authorization_code and refresh_token grants are supported.”Another grant type in the registration.
invalid_client_metadata“Client registration is temporarily unavailable.”Registration is closed for now. Try again later.
invalid_scope“Unsupported scope: …”A scope other than hogmatix:read or hogmatix:schedule.
invalid_target“This authorization server only issues tokens for the Hogmatix MCP endpoint.”A resource other than https://hogmatix.com/mcp.
access_denied“The user declined access.”The user chose Cancel on the consent page.
invalid_grant“Invalid or expired authorization code.”The code was used, expired after 10 minutes, or belongs to another client.
invalid_grant“redirect_uri does not match the authorization request.”A different redirect_uri at /token.
invalid_grant“Invalid refresh token.”Expired, revoked or already rotated. Sign in again.
invalid_scope“Cannot widen the granted scopes.”A refresh asked for a scope the grant doesn't have.
Consent page“This sign-in request has expired” and “Go back to the app you were connecting and start again.”More than 15 minutes passed, or the request was already answered.
too_many_requestsRate limitSee Table 6.

Tool errors

A tool error is a normal result with isError: true and one text item. The text is Hogmatix's message, “Hogmatix returned status.” when there is none, or “Hogmatix could not complete that request.”

Table 22. Tool error messages users see most, grouped by area.

MessageWhat to do
Calls
“MCP error -32602: Input validation error: Invalid arguments for tool …”Fix the arguments to match the schema.
“MCP error -32602: Tool … not found”The tool isn't in this grant's list. Reconnect with the needed scope.
Time
“scheduledAt must be ISO 8601 with a time-zone offset, e.g. 2026-10-01T16:05:00-07:00.”Add the offset or Z.
“scheduledAt is not a valid date.”Check the date.
“scheduledAt must be at least 10 minutes from now.”Pick a later time.
Allowances
“Your plan's monthly usage allowance is used up. More becomes available on …” (also free and trial versions)Wait for the date, or schedule on TikTok and YouTube, which don't use it.
Uploads, imports and links
“Too many active uploads. Finish or cancel one before starting another.”Schedule a pending upload first, or wait for unused ones to clear.
“Your daily upload count limit has been reached.” / “Your daily upload byte limit would be exceeded.” / “Your active upload byte limit would be exceeded.”Wait, or schedule pending uploads.
“Upload capacity is temporarily full. Try again later.”Retry later.
“The uploaded bytes do not match the declared media type …”Declare the file's real type and upload again.
“Upload stopped in state …: …”Start a new upload.
“Hogmatix no longer has this import: it expired or the server restarted. …”Call import_attached_file again.
“That link is not from ChatGPT's file storage, so Hogmatix can't import it. …”Attach the file in ChatGPT, or upload on hogmatix.com.
“The attachment link has expired. Attach the file again.”Attach it again.
“This account already has 5 unused upload links. …”Use a link, or wait up to 30 minutes.
“Hogmatix has no such upload link for this account. …”Create a new link.
Sound check
“… has no sound: ffprobe found no audio track. …”Add a soundtrack and upload again.
“… is effectively silent: …”Fix the audio and upload again.
“… was not posted because Hogmatix could not check its sound. …”Try again shortly.
Scheduling
“This upload was already claimed with different submission settings.”Upload the file again for a different post.
“The existing submission is cancelled; check submission history before uploading new media.”Upload the file again and schedule a new post.
“Long posts with links can't be sent to X. Remove the link and try again.”Remove the link, or use shortform.
“Branded content can't be private: …”Choose public or friends visibility.
“That privacy setting is no longer available for this TikTok account. …”Call get_tiktok_creator_info and choose again.
“This account already has a TikTok post within 2 hours of that time. Pick a later time.”Move the post.
“This would put … TikTok posts for this account inside one 24-hour window. …”Move the post to a later day.
“TikTok needs this account connected again before it can post. …”Reconnect the account on hogmatix.com.
“Could not check this TikTok account's current settings, so nothing was posted. Try again. …”Retry.
Canceling
“Only pending posts can be cancelled.” / “Only a submission that has not started provider work can be cancelled.”The post is already going out or finished.
“profile is required for X.”Pass profile to list_scheduled_posts.

Some failures happen at publishing time rather than when a tool runs. They show in the post's error field in list_scheduled_posts, for example a posting allowance message, “This post missed its scheduled time by more than 6 hours, so it was not posted. Schedule it again.” or “Held back: another post for this TikTok account went out less than 2 hours ago. Reschedule it.”

Security and privacy

  1. No passwords or API keys in the assistant. Users sign in on hogmatix.com, and only a person signed in there can approve a client. Tokens are issued only for https://hogmatix.com/mcp.
  2. Tokens are stored as hashes. Hogmatix keeps only a SHA-256 hash of each access token, refresh token and client secret. Access tokens last an hour; refresh tokens rotate on every use, and reuse of a rotated one revokes the grant.
  3. Every call is checked like a web request. Tools call Hogmatix's own API with the user's token, so the same scope limits, account ownership checks and plan rules apply. The account itself is checked again on every request.
  4. Media stays private. Uploads go to private storage, never to a public URL, and are posted only when a post the user confirmed is due. An upload that is never scheduled is cleared about a day later. Upload links carry their secret in the URL fragment, which browsers don't send to servers.
  5. Imports fetch only from ChatGPT. import_attached_file downloads only from ChatGPT's file hosts and refuses links to private network addresses.

What an assistant receives

An assistant receives only the results of the calls it makes for you. Depending on the call, that can include your connected X, TikTok and YouTube account names and identifiers (listing your accounts can return all of them, even when you ask about one platform), your scheduled and recent posts with their text, media details, times and status, your TikTok account's current posting options, media upload status, and your plan and posting usage. The assistant's provider handles this under its own privacy policy. Details are in the Privacy Policy.

Ending access

Remove Hogmatix in the assistant's settings, reset your Hogmatix password, or email payme@ishti.org to have every assistant's access revoked. See Revocation.

Never send passwords, access tokens or card numbers to support. Hogmatix will never ask for them.

Version history

The server reports its version in serverInfo.version. The current version is 1.0.1.

Table 23. Changes that affect MCP clients.

DateChange
12 November 2026This reference published.
11 November 2026Videos without sound are refused on every platform. Upload and link status report the sound check in audio.
4 November 2026Free plan: any verified, non-disposable email address can connect an assistant.

Product changes are listed in the changelog.

Appendix: JSON schemas

Each entry is the tool exactly as tools/list returns it, including the description the model reads. The default and ChatGPT lists share these definitions. Hosted Claude uses the same definitions for its tools, with one difference: in schedule_tiktok_video, the durationSec description reads “The video's length in seconds. get_upload_link_status returns it as durationSec.”

Server instructions: Default and ChatGPT The instructions field of the initialize result.
Hogmatix schedules posts to the user's connected X, TikTok and YouTube accounts. Posts go out on the user's X, TikTok or YouTube account at the scheduled time, with the visibility the user picks, and can't be undone once published: confirm the account, the exact text or caption, the time and every label with the user before scheduling. For a file the user attached in the chat, call import_attached_file for one platform and schedule that platform's post with the uploadId it returns before importing for the next platform: an import holds upload storage until it is scheduled. A client that can PUT bytes itself uploads in three steps instead: create_media_upload, then PUT each part to the URL from get_upload_part_url, then complete_media_upload. Accounts are connected on https://hogmatix.com, not through these tools.
Server instructions: Hosted Claude The instructions field of the initialize result.
Hogmatix schedules posts to the user's connected X, TikTok and YouTube accounts. Posts go out on the user's X, TikTok or YouTube account at the scheduled time, with the visibility the user picks, and can't be undone once published: confirm the account, the exact text or caption, the time and every label with the user before scheduling. Files attached in this chat can't be passed to Hogmatix. To post a photo or video, call create_upload_link for the platform and give the user the link: they choose the file on a hogmatix.com page, and get_upload_link_status reports when it is ready and returns the uploadId to schedule with. Each platform needs its own upload, and each upload holds upload storage until it is scheduled. Accounts are connected on https://hogmatix.com, not through these tools.
list_accounts Full tools/list entry (default list).
{
  "name": "list_accounts",
  "title": "List connected accounts",
  "description": "List the X, TikTok and YouTube accounts connected to the user's Hogmatix. Call this first: the scheduling tools need an account's profile, openId or channelId. When the request is about one platform, pass platform to list only that platform's accounts.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "platform": {
        "type": "string",
        "enum": [
          "x",
          "tiktok",
          "youtube"
        ],
        "description": "List only this platform's accounts. Omit to list all three."
      }
    },
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "execution": {
    "taskSupport": "forbidden"
  }
}
get_plan Full tools/list entry (default list).
{
  "name": "get_plan",
  "title": "Get plan and posting usage",
  "description": "Show the signed-in user's Hogmatix plan and posting allowance. This tool does not offer subscriptions or change billing.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "$schema": "http://json-schema.org/draft-07/schema#"
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "execution": {
    "taskSupport": "forbidden"
  }
}
get_tiktok_creator_info Full tools/list entry (default list).
{
  "name": "get_tiktok_creator_info",
  "title": "Get TikTok posting options",
  "description": "Read a connected TikTok account's current creator settings live from TikTok: who it posts as, the privacy levels it may post with, its maximum video length and interactions the creator disabled, plus the declaration TikTok requires the creator to see before posting. Call before schedule_tiktok_video and let the user choose from these options.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "openId": {
        "type": "string",
        "minLength": 1,
        "description": "The TikTok account's openId from list_accounts."
      }
    },
    "required": [
      "openId"
    ],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": true
  },
  "execution": {
    "taskSupport": "forbidden"
  }
}
list_scheduled_posts Full tools/list entry (default list).
{
  "name": "list_scheduled_posts",
  "title": "List scheduled posts",
  "description": "List scheduled and recent posts for one platform, with their status. X needs the profile from list_accounts.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "platform": {
        "type": "string",
        "enum": [
          "x",
          "tiktok",
          "youtube"
        ]
      },
      "profile": {
        "type": "string",
        "description": "X only: the profile from list_accounts."
      }
    },
    "required": [
      "platform"
    ],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "execution": {
    "taskSupport": "forbidden"
  }
}
get_upload_status Full tools/list entry (default list).
{
  "name": "get_upload_status",
  "title": "Get media upload status",
  "description": "Check a media upload's state. It is ready to schedule once the state is \"promoted\".",
  "inputSchema": {
    "type": "object",
    "properties": {
      "uploadId": {
        "type": "string",
        "pattern": "^upl_[A-Za-z0-9_-]{1,128}$"
      }
    },
    "required": [
      "uploadId"
    ],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "execution": {
    "taskSupport": "forbidden"
  }
}
import_attached_file Full tools/list entry (default list).
{
  "name": "import_attached_file",
  "title": "Import an attached file",
  "description": "Import a video or image the user attached in this chat into Hogmatix's private storage so it can be scheduled. ChatGPT passes the attachment in file automatically; nothing else is fetched. Use purpose x-media for X, tiktok-video for TikTok or youtube-video for YouTube: each platform needs its own import of the attachment. Each import holds one of the account's upload slots until it is scheduled, so import only for platforms the user chose, and schedule each platform's post before importing for the next. Waits up to about 40 seconds. When state is \"ready\", pass uploadId to schedule_x_post, schedule_tiktok_video (with durationSec, the video's length in seconds; if it is null, ask the user) or schedule_youtube_video. If it is still \"downloading\" or \"uploading\", call get_import_status with importId. Calling again with the same attachment and purpose returns the same import until its upload has been scheduled, then imports it afresh. When the account's upload slots are full, the import fails and asks the user to schedule pending files first; it never deletes other files to make room.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "file": {
        "type": "object",
        "properties": {
          "download_url": {
            "type": "string",
            "description": "ChatGPT's signed link to the attachment. Only links on ChatGPT's file hosts (oaiusercontent.com, chatgpt.com) are accepted."
          },
          "file_id": {
            "type": "string"
          },
          "mime_type": {
            "type": "string"
          },
          "file_name": {
            "type": "string"
          }
        },
        "required": [
          "download_url",
          "file_id"
        ],
        "additionalProperties": false,
        "description": "The file the user attached in the chat. ChatGPT fills this in."
      },
      "purpose": {
        "type": "string",
        "enum": [
          "x-media",
          "tiktok-video",
          "youtube-video"
        ],
        "description": "x-media for X, tiktok-video for TikTok, youtube-video for YouTube."
      }
    },
    "required": [
      "file",
      "purpose"
    ],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": false,
    "openWorldHint": false
  },
  "execution": {
    "taskSupport": "forbidden"
  },
  "_meta": {
    "openai/fileParams": [
      "file"
    ]
  }
}
get_import_status Full tools/list entry (default list).
{
  "name": "get_import_status",
  "title": "Get import status",
  "description": "Check an import started by import_attached_file. Waits up to about 20 seconds while it is still \"downloading\" or \"uploading\". When state is \"ready\", schedule with uploadId; durationSec is the video's length in seconds for schedule_tiktok_video. A \"failed\" import says why in error.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "importId": {
        "type": "string",
        "pattern": "^imp_[A-Za-z0-9_-]{1,128}$"
      }
    },
    "required": [
      "importId"
    ],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "execution": {
    "taskSupport": "forbidden"
  }
}
create_media_upload Full tools/list entry (default list).
{
  "name": "create_media_upload",
  "title": "Start a media upload",
  "description": "Start uploading a video or image to Hogmatix's private storage, from a client that can PUT file bytes itself. For a file the user attached in the chat, use import_attached_file instead. Returns an uploadId, partSize and partCount. For each part (numbered from 1), call get_upload_part_url with the part's SHA-256 (base64), PUT exactly those bytes to the returned URL with the returned headers, then call complete_media_upload. Use purpose x-media for X images or video, tiktok-video for TikTok, youtube-video for YouTube. Each upload holds one of the account's upload slots until it is scheduled; an unfinished upload expires after about 2 hours without activity, and a finished one that is never scheduled is cleared about a day later.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "purpose": {
        "type": "string",
        "enum": [
          "x-media",
          "tiktok-video",
          "youtube-video"
        ]
      },
      "filename": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "mimeType": {
        "type": "string",
        "minLength": 3,
        "maxLength": 100,
        "description": "For example video/mp4, video/quicktime, image/png."
      },
      "byteSize": {
        "type": "integer",
        "exclusiveMinimum": 0
      }
    },
    "required": [
      "purpose",
      "filename",
      "mimeType",
      "byteSize"
    ],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": false,
    "openWorldHint": false
  },
  "execution": {
    "taskSupport": "forbidden"
  }
}
get_upload_part_url Full tools/list entry (default list).
{
  "name": "get_upload_part_url",
  "title": "Register an upload part",
  "description": "Register one part of a media upload and get a short-lived signed URL for it. This records the part's SHA-256 checksum on the upload, marks the upload as uploading and counts toward the upload's part-URL limit. PUT exactly expectedSize bytes to url with the returned headers. If a PUT fails, call again with the same checksum for a fresh URL; a different checksum for the same part is refused.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "uploadId": {
        "type": "string",
        "pattern": "^upl_[A-Za-z0-9_-]{1,128}$"
      },
      "partNumber": {
        "type": "integer",
        "minimum": 1
      },
      "checksumSha256": {
        "type": "string",
        "minLength": 40,
        "maxLength": 64,
        "description": "Base64 SHA-256 of the part's bytes."
      }
    },
    "required": [
      "uploadId",
      "partNumber",
      "checksumSha256"
    ],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": false,
    "openWorldHint": false
  },
  "execution": {
    "taskSupport": "forbidden"
  }
}
complete_media_upload Full tools/list entry (default list).
{
  "name": "complete_media_upload",
  "title": "Finish a media upload",
  "description": "Finish a media upload after every part was PUT. Waits up to a minute for it to be ready (state \"promoted\"). If a part's size or checksum, or the file's type, fails verification, the upload is marked failed and must be started again; if parts are missing, PUT them and call this again.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "uploadId": {
        "type": "string",
        "pattern": "^upl_[A-Za-z0-9_-]{1,128}$"
      }
    },
    "required": [
      "uploadId"
    ],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": false,
    "openWorldHint": false
  },
  "execution": {
    "taskSupport": "forbidden"
  }
}
create_upload_link Full tools/list entry (hosted Claude list).
{
  "name": "create_upload_link",
  "title": "Create an upload link",
  "description": "Create a one-time link to a hogmatix.com page where the user chooses a photo or video on their device and uploads it to Hogmatix's private storage, for one platform. Use purpose x-media for X (images or video), tiktok-video for TikTok or youtube-video for YouTube; accepts lists the file types and sizes that purpose takes. The link takes one file and expires after 30 minutes if unused, and an account can have 5 unused links at once. Returns linkId and url: the user opens url in a browser, and get_upload_link_status with linkId reports when the file is ready to schedule.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "purpose": {
        "type": "string",
        "enum": [
          "x-media",
          "tiktok-video",
          "youtube-video"
        ],
        "description": "x-media for X, tiktok-video for TikTok, youtube-video for YouTube."
      }
    },
    "required": [
      "purpose"
    ],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": false,
    "openWorldHint": false
  },
  "execution": {
    "taskSupport": "forbidden"
  }
}
get_upload_link_status Full tools/list entry (hosted Claude list).
{
  "name": "get_upload_link_status",
  "title": "Get upload link status",
  "description": "Check an upload link from create_upload_link. Waits up to about 20 seconds while the user hasn't finished uploading. state is \"waiting\" (the page wasn't opened or no file was chosen yet), \"uploading\", \"ready\" (schedule with uploadId), \"failed\" (error says why) or \"expired\" (the link wasn't used within 30 minutes). When ready, durationSec is a video's length in seconds for schedule_tiktok_video; it is null when the browser couldn't read it, and then the length has to come from the user.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "linkId": {
        "type": "string",
        "pattern": "^lnk_[A-Za-z0-9_-]{22}$"
      }
    },
    "required": [
      "linkId"
    ],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "execution": {
    "taskSupport": "forbidden"
  }
}
schedule_x_post Full tools/list entry (default list).
{
  "name": "schedule_x_post",
  "title": "Schedule an X post",
  "description": "Schedule a post, thread or long post on a connected X account. At the scheduled time Hogmatix publishes it on X, where it is public; Hogmatix never deletes published posts from X, and until then cancel_scheduled_post can cancel it. For a thread, separate the posts with a blank line. Optionally attach media uploaded with purpose x-media. Confirm the account, the exact text and the time with the user first.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "profile": {
        "type": "string",
        "minLength": 1,
        "description": "The X profile from list_accounts."
      },
      "text": {
        "type": "string",
        "minLength": 1,
        "maxLength": 25000
      },
      "format": {
        "type": "string",
        "enum": [
          "shortform",
          "thread",
          "longform"
        ],
        "default": "shortform"
      },
      "scheduledAt": {
        "type": "string",
        "description": "ISO 8601 with a time-zone offset, at least 10 minutes ahead."
      },
      "uploadId": {
        "type": "string",
        "pattern": "^upl_[A-Za-z0-9_-]{1,128}$"
      }
    },
    "required": [
      "profile",
      "text",
      "scheduledAt"
    ],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": false,
    "openWorldHint": true
  },
  "execution": {
    "taskSupport": "forbidden"
  }
}
schedule_tiktok_video Full tools/list entry (default list).
{
  "name": "schedule_tiktok_video",
  "title": "Schedule a TikTok video",
  "description": "Schedule an uploaded video (purpose tiktok-video) on a connected TikTok account. At the scheduled time Hogmatix publishes it on TikTok; Hogmatix can't remove a published video, and until then cancel_scheduled_post can cancel it. Every choice is explicit, as TikTok's Direct Post rules require: privacy (one of the account's creator-info options), the AI-generated label, commercial disclosure (yourBrand = promoting the creator's own business; brandedContent = paid promotion of a third party, only with public or friends visibility) and each interaction. Hogmatix re-checks the creator's settings and its posting-density rules. Before calling, show the user: Posting as creator_nickname (@creator_username) from get_tiktok_creator_info; the caption and time; the chosen privacy option; the comment, Duet and Stitch settings; the disclosure and AI-generated choices; and the declaration \"By posting, you agree to TikTok's Music Usage Confirmation.\" (with brandedContent: \"By posting, you agree to TikTok's Branded Content Policy and Music Usage Confirmation.\"). Then get the user's explicit go-ahead, even when the request states every choice.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "openId": {
        "type": "string",
        "minLength": 1
      },
      "uploadId": {
        "type": "string",
        "pattern": "^upl_[A-Za-z0-9_-]{1,128}$"
      },
      "caption": {
        "type": "string",
        "maxLength": 2200
      },
      "scheduledAt": {
        "type": "string",
        "description": "ISO 8601 with a time-zone offset, at least 10 minutes ahead."
      },
      "privacyLevel": {
        "type": "string",
        "enum": [
          "PUBLIC_TO_EVERYONE",
          "MUTUAL_FOLLOW_FRIENDS",
          "FOLLOWER_OF_CREATOR",
          "SELF_ONLY"
        ]
      },
      "aiGenerated": {
        "type": "boolean"
      },
      "yourBrand": {
        "type": "boolean"
      },
      "brandedContent": {
        "type": "boolean"
      },
      "allowComments": {
        "type": "boolean"
      },
      "allowDuet": {
        "type": "boolean"
      },
      "allowStitch": {
        "type": "boolean"
      },
      "durationSec": {
        "type": "number",
        "exclusiveMinimum": 0,
        "description": "The video's length in seconds. import_attached_file returns it as durationSec."
      }
    },
    "required": [
      "openId",
      "uploadId",
      "caption",
      "scheduledAt",
      "privacyLevel",
      "aiGenerated",
      "yourBrand",
      "brandedContent",
      "allowComments",
      "allowDuet",
      "allowStitch",
      "durationSec"
    ],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": false,
    "openWorldHint": true
  },
  "execution": {
    "taskSupport": "forbidden"
  }
}
schedule_youtube_video Full tools/list entry (default list).
{
  "name": "schedule_youtube_video",
  "title": "Schedule a YouTube video",
  "description": "Schedule an uploaded video (purpose youtube-video) on a connected YouTube channel. At the scheduled time Hogmatix uploads it to YouTube; Hogmatix can't remove an uploaded video, and until then cancel_scheduled_post can cancel it. Confirm the channel, the title, the privacy and the time with the user first.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "channelId": {
        "type": "string",
        "minLength": 1
      },
      "uploadId": {
        "type": "string",
        "pattern": "^upl_[A-Za-z0-9_-]{1,128}$"
      },
      "title": {
        "type": "string",
        "minLength": 1,
        "maxLength": 100
      },
      "description": {
        "type": "string",
        "maxLength": 5000,
        "default": ""
      },
      "privacyStatus": {
        "type": "string",
        "enum": [
          "private",
          "unlisted",
          "public"
        ]
      },
      "madeForKids": {
        "type": "boolean"
      },
      "scheduledAt": {
        "type": "string",
        "description": "ISO 8601 with a time-zone offset, at least 10 minutes ahead."
      }
    },
    "required": [
      "channelId",
      "uploadId",
      "title",
      "privacyStatus",
      "madeForKids",
      "scheduledAt"
    ],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": false,
    "openWorldHint": true
  },
  "execution": {
    "taskSupport": "forbidden"
  }
}
cancel_scheduled_post Full tools/list entry (default list).
{
  "name": "cancel_scheduled_post",
  "title": "Cancel a scheduled post",
  "description": "Cancel a post that has not been published yet. Cancelling is permanent: the post can't be restored, and posting it later means scheduling a new post (with its media imported or uploaded again). Posts already on X, TikTok or YouTube cannot be recalled here.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "platform": {
        "type": "string",
        "enum": [
          "x",
          "tiktok",
          "youtube"
        ]
      },
      "id": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_-]{1,128}$",
        "description": "The id from list_scheduled_posts or the schedule result."
      }
    },
    "required": [
      "platform",
      "id"
    ],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "execution": {
    "taskSupport": "forbidden"
  }
}

How to cite

Hogmatix. “Hogmatix MCP server: documentation and tool reference.” Server version 1.0.1. Updated 12 November 2026. https://hogmatix.com/docs/mcp