MCP tools reference

Work in progress — connector not yet publicly available. Email hello@rheos.app for early access.

This is the full technical reference for everything the Rheos connector can do. If you’re an end user, you probably don’t need this — your AI chat picks the right tool automatically. It’s useful if you’re building agent workflows or want to know exactly what’s possible. This page lists every tool the Rheos MCP server registers, with the parameters your assistant needs to know about. Each tool returns a JSON payload — the shapes shown below are summaries; call the tool and inspect the response for the full schema.

Almost every tool takes a brand_id (short ID like default_f7634e61). Start any session with rheos_list_brands to discover valid IDs, or call rheos_get_context to grab brand identity, audiences, themes and reference data in one call.

Posts

CRUD for posts, pillars, campaigns and other Rheos records. resource_type selects the collection.

`rheos_list`

List records of a given type for the user or brand.

resource_type — "posts" | "pillars" | "campaigns" | "brands" | ...
brand_id (optional) — filter to one brand
status (optional) — e.g. "draft", "idea", "scheduled", "published"
limit (optional)
include_deleted (optional) — set to true to include soft-deleted assets; defaults to false

`rheos_get`

Fetch a single record by id.

resource_type — same enum as rheos_list
id — record id

Soft-deleted assets are not returned.

`rheos_create`

Create a record. For resource_type="posts" this is the canonical drafting endpoint — pass brand_id, textBody, and any optional formula fields (intent, hookId, ctaId) you want to store.

{
  "resource_type": "posts",
  "brand_id": "default_f7634e61",
  "fields": {
    "textBody": "We just shipped...",
    "intent": "announce",
    "hookId": "before-after",
    "ctaId": "learn-more",
    "channels": ["linkedin", "instagram"],
    "assetIds": ["asset_abc123"]
  }
}

`rheos_update`

Patch fields on an existing record. Use this after rheos_accept_idea to write the post body, or to edit a draft before scheduling.

resource_type, id, fields — partial update object

Ideation

Formula-aware idea generation. Ideas live as posts with status="idea"; accepting one flips it to status="draft".

`rheos_brainstorm`

Calls the Genkit postBrainstormFlow. Returns a list of formula-aware ideas suitable for picking one and writing the body yourself with rheos_create.

brand_id (required)
topic (optional) — seed concept
count (optional) — defaults to a small batch

`rheos_generate_ideas`

Persists a batch of new ideas (posts with status="idea") and returns their idea_ids. Use when you want the user to pick from a queue rather than inline-brainstorm.

brand_id (required)
count, intent, hook_type, audience_name, theme_title (optional) — bias the set toward a formula slot, audience or theme

`rheos_accept_idea`

Flips one idea from status="idea" to status="draft". After accepting, write the body in the brand voice and save it via rheos_update.

idea_id (required)

`rheos_refresh_idea`

Regenerates a single idea in place — keeps the id, replaces the content.

idea_id (required)

Publishing

Move a draft to scheduled or live across one or more channels.

`rheos_schedule_post`

Queue a post for a future time. Status moves to scheduled; the backend cron picks it up at scheduled_at. The post publishes to the channels already set on the draft.

post_id (required)
scheduled_at — ISO 8601 timestamp

If any channel set on the post has no connected social account, the call is rejected before scheduling:

{ "error": "channel_not_connected", "channels": ["twitter"] }

Call rheos_get_platforms (or rheos_get_context) to see which channels are connected. Use rheos_connect_platform to connect any missing channel before retrying.

This guard fails open by design. If connectedness cannot be determined — for example, because the post record is missing, the post has no brand attribution, or a read fails — the post still schedules. It blocks only when a channel is definitely not connected.

`rheos_publish_post`

Publish immediately to the channels set on the draft. Returns per-channel publishResults — inspect results[].error if any channel fails.

post_id (required)

`rheos_cancel_scheduled`

Pull a scheduled post back to draft so you can edit or delete it.

post_id (required)

`rheos_connect_platform`

Returns a dashboard OAuth deep-link the user can open in a browser to connect Instagram, LinkedIn, Facebook, etc.

channel — "instagram" | "linkedin" | "facebook" | ...
brand_id (required)

Brands & identity

Read and update the brand identity document, the sources that feed it, and the metadata stored on the brand record.

`rheos_list_brands`

List every brand in the org (both business and personal). Call this first in any drafting flow — every subsequent tool needs a brand_id.

`rheos_get_context`

Bundle call: returns the brand record, identity document, audiences, themes, formulas and reference data in one response. Audiences come from audience boxes or the content strategy; themes come from the content strategy. Legacy pillars are the last-resort fallback. The audiences and themes fields remain arrays of strings, with empty and whitespace-only values omitted.

brand_id (required)

`rheos_view_brand_document`

Read the freeform markdown identity document for a brand — the synthesised output of all sources.

brand_id (required)
version (optional) — pick an older version

`rheos_view_brand_sources`

List every source attached to the brand (website scrape, AI import, uploaded docs) with status and timestamps.

brand_id (required)

`rheos_view_source`

Read the full content of a single source.

brand_id, source_id

`rheos_update_ai_import`

Write or replace the AI-import source — the one external write path into the brand’s source set. Personal brands use this instead of rheos_scrape_website.

brand_id (required)
content — markdown body

`rheos_scrape_website`

Scrape a URL via Firecrawl (Cheerio fallback) and populate the brand’s website source. Business brands only.

brand_id (required)
url (required)

`rheos_trigger_identity_doc_flow`

Synthesise all active sources into the brand identity document. Call after populating sources via rheos_update_ai_import or rheos_scrape_website.

brand_id (required)
regenerate (optional) — force a fresh synthesis even if cached

`rheos_update_brand_metadata`

Set structured fields on the brand record (name, tone, audience labels, etc.) without re-running the full identity flow.

brand_id (required)
fields — partial metadata patch

Images

Generate, iterate, upload and save image assets. Generated images return inline as base64; saved assets get an asset_id you pass into rheos_create.

Asset read responses omit the raw embedding vector. Soft-deleted assets are excluded by default; set include_deleted: true on rheos_list when you need to include them.

`rheos_image_generate`

Generate or iterate an image inside an ephemeral session. Pass iterate_from_generation_id to refine instead of starting fresh.

brand_id (required)
prompt (required)
session_id (optional) — resume an existing session
iterate_from_generation_id (optional)

`rheos_image_save_asset`

Promote a generation into the brand’s asset library so it can be attached to a post.

session_id, generation_id — from the previous rheos_image_generate call

`rheos_image_get_session`

Read back every image generated in a session — the options themselves, their prompts, and which ones were kept. Use it when the generation response has scrolled out of the conversation: without it the only way to see those options again is to generate them again.

session_id (required) — from rheos_image_generate
limit (optional) — newest first, default 20, max 50

Each generation returns generation_id, image_url, prompt, status and saved_asset_id (set once promoted). The response also carries a markdown field of image links, so an assistant whose interface drops inline images can still show the options.

`rheos_upload_image`

Store an externally-generated image (PNG / JPEG / WebP, ≤10 MB) as a Rheos asset. Returns an asset_id.

brand_id (required)
image_base64 or image_url
alt_text (optional)

`rheos_upload_video`

Store a video (MP4 / MOV / WebM, ≤25 MB) as a Rheos asset. Returns an asset_id you pass to rheos_create as assetIds. The format is identified from the file’s own bytes, not its extension or the server’s content type.

brand_id (required)
video_base64 or video_url — exactly one
alt_text, filename, source_note (optional)

`rheos_draft_post_from_image`

One-shot: upload an image and draft a caption + post in a single call. Preferred over rheos_upload_image + rheos_create when the user already has a topic in mind.

brand_id (required)
image_base64 or image_url
topic (optional)
hook_type (optional) — formula hook label

Video

Session-based video editing: get the current scenes, edit them, render via AWS Lambda, then have Gemini review the MP4.

The video tools below are not yet on the customer tool surface — they are documented here because the API is stable and the group is next in line to open up. To get an existing video file into Rheos today, use rheos_upload_video.

`rheos_video_get_session`

Fetch the current scenes and metadata for a video session.

session_id (required)

`rheos_video_update_scenes`

Apply scene-level edits (text layers, timing, asset swaps). For AI-suggested edits prefer rheos_video_apply_suggestions — it preserves layer ids.

session_id (required)
scenes — full scene array

`rheos_video_render`

Kick off the Lambda render. Returns render_id + bucket_name — poll progress with rheos_video_render_progress every 3–5 seconds.

session_id (required)

`rheos_video_render_progress`

Poll a render. Returns done, progress, and (when complete) the MP4 URL.

render_id, bucket_name

`rheos_video_review`

Send the rendered MP4 to Gemini for critique. Returns text suggestions you can feed back into rheos_video_apply_suggestions.

session_id (required)

`rheos_video_apply_suggestions`

Patch scenes from a review’s suggestions. Preserves layer ids so animations don’t reset. After applying, re-render with rheos_video_render.

session_id, suggestions — from rheos_video_review

Search

`rheos_search_posts`

Substring search over a brand’s posts (drafts + scheduled + published).

brand_id (required)
query (required)

`rheos_search_assets`

Basic text matching against the asset library (filename, alt text, prompt). Soft-deleted assets are excluded. Every matching result includes its own score.

brand_id (required)
query (required)

When nothing matches, the tool returns:

{
  "query": "product shots",
  "results": [],
  "error": "no_assets_matched",
  "next_step": "No assets matched; broaden the query or generate an image instead."
}

This is a real no-match result, not a fallback asset list. Broaden the query or generate an image instead of retrying the same query unchanged.

Reference

Small read-only helpers split out so they don’t bloat rheos_get_context.

`rheos_get_capabilities`

Report which capabilities are usable right now — generation, uploads, video, publishing and analytics — before committing to a workflow. Cheap, read-only, and makes no outbound calls.

brand_id (optional) — publishing readiness is brand-scoped; defaults to the org’s primary brand

Each capability returns granted (is it on your tool surface), healthy (is it usable this moment) and a plain-language reason when either is false — for example no connected channel, or no credits remaining. Call it first and you avoid discovering a limit by hitting an error mid-task.

`rheos_get_formulas`

Return the static formula tree: 8 intents × 35+ hooks × 10 CTAs.

Retired on 22 Aug 2026 and no longer on the customer tool surface. The assistant you are already talking to writes the post; a fixed formula tree only competed with it for attention. Nothing replaces it — describe the post you want in your own words.

`rheos_list_audiences`

Return the brand’s audiences with the source tier that answered the call.

brand_id (required)

{
  "audiences": [
    { "name": "Founders", "description": "...", "pains": ["..."], "desires": ["..."] }
  ],
  "source": "audience_boxes"
}

name is required on each audience. description, pains and desires are optional. source is "audience_boxes" | "content_strategy" | "legacy_pillars" | "none". It identifies current audience boxes, the content strategy, the legacy pillars fallback, or no data.

Breaking change (19 Aug 2026): audiences entries were previously plain strings and are now objects (name plus optional detail). The source vocabulary also changed — it used to be "brand_pillars" | "org_pillars"; neither value is emitted any more.

`rheos_list_themes`

Return the brand’s themes with the source tier that answered the call.

brand_id (required)

{
  "themes": [
    { "title": "Operations", "description": "...", "icon": "..." }
  ],
  "source": "content_strategy"
}

title is required on each theme. description and icon are optional. source is "content_strategy" | "legacy_pillars" | "none". It identifies the content strategy, the legacy pillars fallback, or no data.

Breaking change (19 Aug 2026): themes entries were previously plain strings and are now objects (title plus optional detail). The source vocabulary also changed — it used to be "brand_pillars" | "org_pillars"; neither value is emitted any more.

`rheos_get_platforms`

List connected social platforms for the user with token status and expiry.

`rheos_get_credits`

Return the user’s current credit balance and the credit cost of common operations.

Not on the customer tool surface. Credit reporting is being reworked; ask about capability availability with rheos_get_capabilities instead, which reports whether image generation is usable right now.

`rheos_fetch_docs`

Fetch a page from rheos.app/docs as markdown — useful for grounding an assistant in product help articles. Pass no URL to get the docs index.

url (optional) — must be on rheos.app

Conventions

Errors include error and may include hint, next_step, or tool-specific fields such as channels. When present, hint tells the caller which tool to invoke next (e.g. “Call rheos_list_brands first”).
All timestamps are ISO 8601 in UTC.
brand_id for personal brands is the user’s user_id; for business brands it’s the short id from rheos_list_brands.
Credits are deducted on tool success, not invocation. A failed rheos_image_generate won’t charge you.

​Posts

​rheos_list

​rheos_get

​rheos_create

​rheos_update

​Ideation

​rheos_brainstorm

​rheos_generate_ideas

​rheos_accept_idea

​rheos_refresh_idea

​Publishing

​rheos_schedule_post

​rheos_publish_post

​rheos_cancel_scheduled

​rheos_connect_platform

​Brands & identity

​rheos_list_brands

​rheos_get_context

​rheos_view_brand_document

​rheos_view_brand_sources

​rheos_view_source

​rheos_update_ai_import

​rheos_scrape_website

​rheos_trigger_identity_doc_flow

​rheos_update_brand_metadata

​Images

​rheos_image_generate

​rheos_image_save_asset

​rheos_image_get_session

​rheos_upload_image

​rheos_upload_video

​rheos_draft_post_from_image

​Video

​rheos_video_get_session

​rheos_video_update_scenes

​rheos_video_render

​rheos_video_render_progress

​rheos_video_review

​rheos_video_apply_suggestions

​Search

​rheos_search_posts

​rheos_search_assets

​Reference

​rheos_get_capabilities

​rheos_get_formulas

​rheos_list_audiences

​rheos_list_themes

​rheos_get_platforms

​rheos_get_credits

​rheos_fetch_docs

​Conventions

Posts

`rheos_list`

`rheos_get`

`rheos_create`

`rheos_update`

Ideation

`rheos_brainstorm`

`rheos_generate_ideas`

`rheos_accept_idea`

`rheos_refresh_idea`

Publishing

`rheos_schedule_post`

`rheos_publish_post`

`rheos_cancel_scheduled`

`rheos_connect_platform`

Brands & identity

`rheos_list_brands`

`rheos_get_context`

`rheos_view_brand_document`

`rheos_view_brand_sources`

`rheos_view_source`

`rheos_update_ai_import`

`rheos_scrape_website`

`rheos_trigger_identity_doc_flow`

`rheos_update_brand_metadata`

Images

`rheos_image_generate`

`rheos_image_save_asset`

`rheos_image_get_session`

`rheos_upload_image`

`rheos_upload_video`

`rheos_draft_post_from_image`

Video

`rheos_video_get_session`

`rheos_video_update_scenes`

`rheos_video_render`

`rheos_video_render_progress`

`rheos_video_review`

`rheos_video_apply_suggestions`

Search

`rheos_search_posts`

`rheos_search_assets`

Reference

`rheos_get_capabilities`

`rheos_get_formulas`

`rheos_list_audiences`

`rheos_list_themes`

`rheos_get_platforms`

`rheos_get_credits`

`rheos_fetch_docs`

Conventions