Server reference

For people building MCP clients and agents. If you use Claude, ChatGPT or another off-the-shelf client, you don’t need any of this.

Endpoint: https://api.adventur.ai/mcp
Transport: Streamable HTTP, stateless, JSON responses
Protocol versions: 2025-11-25, 2025-06-18, 2025-03-26
Authentication: OAuth 2.1 bearer tokens (PKCE S256, dynamic client registration)
Server name: adventurai (AdVentur.ai)
Tools: 65, filtered by the connection's scopes

Transport

The server speaks Streamable HTTP at a single endpoint, https://api.adventur.ai/mcp. It is stateless: send JSON-RPC 2.0 messages with POST, and every response is a single application/json body rather than an SSE stream. There are no session IDs and no server-initiated messages, so any HTTP client works and requests can be retried. JSON-RPC batches (an array of messages) are accepted. GET and DELETE return 405, since there is no stream to open and no session to end. Browser requests from origins other than AdVentur.ai and known MCP clients get 403.

curl -s https://api.adventur.ai/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":1,"method":"tools/list"}'

Send MCP-Protocol-Version on every request after initialize. An unsupported version gets 400.

Methods

Method	Notes
`initialize`	Returns server info, capabilities (`tools`), the negotiated protocol version and the server instructions below.
`notifications/initialized`	Accepted with `202`.
`ping`	Returns an empty result.
`tools/list`	The tools the token’s scopes allow, with JSON Schema inputs and annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`).
`tools/call`	Runs one tool. Results are a single `text` content item holding JSON.

Discovery

URL	What it is
`https://api.adventur.ai/.well-known/oauth-protected-resource/mcp`	RFC 9728 protected resource metadata for the MCP endpoint.
`https://api.adventur.ai/.well-known/oauth-authorization-server`	RFC 8414 authorization server metadata.
`https://api.adventur.ai/oauth/register`	Dynamic client registration.
`https://api.adventur.ai/oauth/authorize`	Authorization endpoint (PKCE S256 required).
`https://api.adventur.ai/oauth/token`	Token endpoint (`authorization_code`, `refresh_token`).
`https://api.adventur.ai/oauth/revoke`	Token revocation.

See Authentication and permissions for the full flow.

Errors

Transport and auth errors are HTTP statuses. 401 means a missing, expired or revoked token and carries a WWW-Authenticate header pointing at the resource metadata; refresh the token or sign in again.
Protocol errors (unknown method, bad params, unknown tool) are JSON-RPC errors. Calling a tool whose scope wasn’t granted returns an invalid params error that names the missing permission.
Tool errors come back as a normal result with isError: true and a JSON text body such as {"status":422,"error":"…"}, so the model can read what went wrong and fix its input. Common statuses: 400/422 invalid input, 402 the plan doesn’t allow it or credits ran out, 403 missing permission, 404 not found, 409 conflict (for example the post was already approved), 429 rate limited.

Rate limits

Each user can make 60 tool calls a minute across all their connections. Individual tools can have tighter limits (research and media imports, for example). Over the limit, the call returns a tool error reading Rate limit exceeded. Retry after N seconds.

Server instructions

Sent with initialize so models know how the tools fit together. When some tools are hidden because their scope wasn’t granted, the server appends a note naming them.

Tools act on the AdVentur.ai workspace the user connected, limited to the permissions they granted.
Read tools cover the home brief, inspiration opportunities, strategy, posts, analytics and connected accounts.
To schedule a post: create_draft_post (lands in Review as pending approval), then approve_post_group, which schedules it to the best slot or to scheduledForUtc.
To revise a draft, use update_post or update_post_group; rewrite_post suggests AI variations and spends credits. Confirm the copy and time with the user before approving, and reject_post_group only when the user asks.
Each post must fit its platform's limit (X 280 as X counts them, links 23 and emoji 2; LinkedIn 3000; Instagram and TikTok 2200; Bluesky 300; Threads 500).
For X copy that runs longer, create_x_thread drafts a thread, splitting long text for you; its follow-ups publish as replies to the first post, and approving it approves the whole thread.
An X post can set replySettings to everyone (anyone; the default), following (accounts you follow), mentionedUsers or verified; one stored value is sent on every tweet in a thread when it is scheduled or posted now.
create_branded_image and create_carousel render on-brand images and carousels (PNG, SVG, PDF) from copy you write, in about a second; list_visual_options shows formats and templates, and an aiBackground adds an AI-generated image that costs money.
To post a visual, pass its postMedia as media to create_draft_post or update_post; it goes out with the post when it publishes.
create_app_screenshot frames a screenshot of the user's app or site in a Mac-style browser window on the brand background, with a headline, for posts that show the product.
Instagram posts need at least one image (square or 4:5 portrait works best) or a video, which posts as a Reel; Facebook Page posts can be text, images or a video (a vertical video of 3 to 90 seconds posts as a Reel). Bluesky posts are up to 300 characters with up to 4 JPEG or PNG images and no video; links, hashtags and @handles become clickable.
To post a video: import_media_from_url for a public link (up to 300 MB), or create_media_upload, PUT the file to its uploadUrl and complete_media_upload; either returns an asset to pass as media.
TikTok takes a video or 1-35 JPEG, WebP or PNG photos; drafts land in the TikTok inbox so the creator finishes them in the TikTok app.
Direct Post to the TikTok profile is only available from the composer in the app (privacy, commercial-content disclosure and Music Usage Confirmation) — do not set postMode to direct from here.
Video goes out on X, LinkedIn (MP4 only), Facebook, Instagram, TikTok and YouTube; X, LinkedIn, Instagram, TikTok and YouTube finish it within a few minutes of publishing, so the post shows awaiting_platform until then.
A YouTube post is a video upload (copy is the description, youtube.title the title); a vertical or square video up to 3 minutes posts as a Short.
For post ideas: get_trending_topics reads the latest trends report for free, find_trending_topics researches live news in the user's niche (spends credits) and returns hot takes with draft posts, and list_viral_post_formats gives proven X and LinkedIn formats with templates to write from, and get_platform_algorithm_hints says what each platform's feed rewards and punishes right now.
For the brand kit: find_brand_kit_on_website suggests one, confirm it with the user, save it with update_brand_kit, then create_branded_image to preview it.
To publish straight away instead of scheduling: approve_post_group with autoSchedule: false, then post_now for each post; only do this when the user asks for it now. post_now refuses a post that isn't approved.
For engagement on X: refresh_reply_inbox pulls new replies, mentions and community posts and drafts replies (spends credits), list_reply_inbox shows them, and update_reply_draft or draft_reply revise a draft. send_reply posts a reply to a mention only after the user approves its exact text; community posts are replied to by the user on X through replyOnXUrl.
To read a post on X from its link (x.com pages can't be fetched directly): get_x_post, with includeMedia for its photos and videos, or get_x_thread for the whole thread and its replies; both spend half a credit per post X returns.
To launch a product: create_launch_kit writes the Product Hunt listing and Show HN post to paste, drafts launch posts into Review and returns a day-by-day plan (spends credits); approve each post with its step's scheduledForUtc so it goes out on plan, and tick steps off with update_launch_step.
For the user's own X posts after they're published: get_x_automation_rules and update_x_automation_rules set standing rules that natively repost the ones that did well and remove the ones nobody saw, run_x_automation shows what those rules would do to the posts they have right now, and list_x_automation_runs shows what they decided before. A rule starts switched off and in dry run, and run_x_automation is always a preview — it changes nothing on X. Deleting a post on X can't be undone, so show the user what a run would pick and leave dryRun true until they are happy with the thresholds; taking a rule live is theirs to do in the app. Nothing here deletes anything itself, and none of it can change autonomy settings.
To delete one X post the user names, by its link or its postId: delete_x_post. A live post is deleted on X for good, so confirm the exact post with the user first; a post that hasn't gone out yet is just taken off the schedule.