Developer docs

Connect an AI agent to Suamuka MCP

Suamuka exposes a remote Model Context Protocol server for authenticated agents. Agents can plan a calendar, draft and schedule posts, publish through Zernio, and build complete photo-slide projects — including reusable themes, layouts, components, folders, uploaded images, slides, and individual elements.

1. Add a server

Create a remote MCP connection

In your agent host, add a remote HTTP MCP server and paste the endpoint above. For local development, expose your Herd site through HTTPS if the agent runs outside this machine.

2. Authorize

Sign in and approve access

The agent should discover Suamuka's OAuth metadata, open the browser authorization flow, and receive a bearer token. Tools always act as the approving Suamuka user.

3. Use tools

Let the agent discover capabilities

After authorization, ask your host to list tools from the server. Suamuka returns JSON schemas for every supported action, so the agent can validate inputs before calling them.

Available tools

Every tool acts on the OAuth-authenticated Suamuka user.

Tool	What it does
Content planning & drafting
create_post_tool	Create a local AI draft post.
list_posts_tool	List posts, optionally filtered by status.
update_post_tool	Edit a draft or editable Zernio-backed post.
delete_post_tool	Delete a post owned by the authenticated user.
plan_content_batch_tool	Report how many posting slots are open and when they fall.
draft_posts_batch_tool	Create several drafts at once against planned slot datetimes.
generate_platform_content_tool	Write real per-platform captions for an existing post.
get_trends_tool	Ground new ideas in current trends before drafting.
Scheduling & publishing
schedule_post_tool	Schedule an existing post by exact time or available slot.
list_schedule_tool	Inspect active platforms, posting settings, and upcoming slots.
submit_post_to_zernio_tool	Submit a Suamuka draft to Zernio as a draft, scheduled post, or immediate post.
list_platforms_tool	List platform definitions available in Suamuka.
upsert_platform_tool	Create or update a platform definition.
delete_platform_tool	Delete a platform definition by slug.
update_platform_schedule_tool	Create or update a user's platform posting schedule.
Slide library
list_slide_library_tool	List reusable themes, layouts, and components with stable references.
manage_slide_library_folder_tool	Create, rename, or delete component folders. Deleting a folder keeps its components in Unfiled.
create_slide_library_item_tool	Create a custom theme, layout, or component with a stable generated reference.
update_slide_library_item_tool	Rename or replace a custom definition; also move components between folders.
delete_slide_library_item_tool	Delete an unused custom item. In-use references and built-ins are protected.
Video Studio
list_video_projects_tool	List your video projects and editor links.
get_video_project_tool	Read the editable brief, story guide, scenes, assets, render status and current version. Signed media links expire after 15 minutes.
create_video_project_tool	Save an agent-written brief, story guide and scenes as a new video project.
update_video_project_tool	Update brief fields or replace the story guide and ordered scene list. Keep scene IDs to preserve assets; omitted scenes are archived.
update_video_scene_tool	Edit one scene or field while preserving the rest. Changed scripts or visuals mark old assets as needing replacement.
create_video_project_asset_upload_tool	Get a signed multipart upload URL for an image, voiceover or clip made elsewhere. Send the file directly; do not put large files in tool arguments.
manage_video_project_asset_tool	Select or clear scene assets, or pin up to three shared reference images.
assemble_video_project_tool	Queue an MP4 from existing selected media. Missing assets must be uploaded first.
review_video_project_generation_tool	Accept or discard a ready version after reviewing its output. Nothing is published.
Slide projects
list_slide_projects_tool	List owned photo-slide projects and their editor links.
get_slide_project_tool	Read a complete suamuka.slides/1.0 document.
render_slide_project_tool	Render one slide as an inline PNG and a 24-hour download link at the project size. A 9:16 project can also render a centred 1080x1350 crop; photos must be uploaded project assets.
create_slide_project_tool	Create a validated slide project from reusable library references, in a 9:16, 4:5, 3:4, 1:1, 16:9 or 1.91:1 canvas.
duplicate_slide_project_tool	Copy a project into a new draft with fresh project, slide, and element IDs.
set_slide_project_theme_tool	Apply a library theme without replacing the rest of the document.
manage_slide_tool	Add, update, duplicate, delete, or reorder individual slides.
manage_slide_element_tool	Add, update, delete, or reorder components on one slide.
update_slide_project_tool	Validate and replace an owned slide project document.
delete_slide_project_tool	Permanently delete an owned project and its attached media.
Approval inbox
submit_approval_requests_tool	Ask before acting: send the exact post, reply, comment or message, where it goes, and why. The user approves, edits or rejects it in the app.
list_approval_requests_tool	List approved requests to act on, or rejected and edited ones to learn from.
claim_approval_request_tool	Claim one approved request right before acting, so it is never done twice.
report_approval_result_tool	Report done with the live link, or failed with a reason.
Inspiration
save_inspirations_tool	Save good posts by other people. Send the text you read from the post or screenshot; links are never fetched.
search_inspirations_tool	Find saved posts by words, platform, tag, or format before drafting.
delete_inspiration_tool	Delete one saved Inspiration item.
Slide assets
list_slide_project_assets_tool	List uploaded project images, URLs, metadata, and photo-element usages.
upload_slide_project_asset_tool	Upload base64 JPEG, PNG, or WebP data up to 10 MB to an owned project.
attach_slide_project_asset_tool	Set a photo element's source URL, asset ID, and accessible alt text.
delete_slide_project_asset_tool	Delete an unused image; attached assets are protected.
Settings & support
get_ai_generation_settings_tool	Read every AI context field and a ready-to-use prompt block.
update_ai_generation_settings_tool	Set, preserve, or clear individual AI context fields.
save_post_examples_tool	Save the user's own posts as example posts for one platform, so drafts there copy that voice.
delete_post_example_tool	Delete one example post.
get_notification_settings_tool	Read notification settings.
update_notification_settings_tool	Update Telegram notification settings.
get_profile_settings_tool	Read profile settings and plan summary.
update_profile_settings_tool	Update profile name and email.
list_support_tickets_tool	Check existing support reports before filing a new one.
submit_support_ticket_tool	File a support ticket in the user's own words and return its reference.

Generic client shape

MCP hosts use different config names. If yours accepts JSON, map these values into its remote server format.

{
  "name": "suamuka",
  "transport": "http",
  "url": "https://www.suamuka.com/mcp/suamuka",
  "auth": "oauth"
}

Operational notes

Video Studio tools save supplied content, upload files and assemble existing media without calling AI or spending Suamuka AI credits. Your external agent or media provider may charge separately. Suamuka in-app assistant messages still use chat credits.
For video edits, read get_video_project_tool first and pass its project.version as expected_version. Brief fields are partial. A supplied scenes array replaces the active order: include every scene to keep, preserve existing IDs, and omit IDs only for new scenes.
Video workflow: write the brief and connected scenes, upload externally generated media, select assets, assemble, poll until ready, inspect the signed media link, then accept. Use include_history:true to review generated text candidates.
Use HTTPS for remote or public agent hosts.
Do not share bearer tokens or OAuth client secrets in prompts.
List the slide library before writes and use only returned stable references.
Use focused slide tools for small edits; use full document replacement for bulk changes.
Image uploads accept JPEG, PNG, and WebP data up to 10 MB. Arbitrary remote URL fetching is disabled.
Deletion is guarded: built-ins are immutable, and in-use library items or assets cannot be removed.
Published posts cannot be edited; Zernio submissions require saved credentials and account mappings.

Slide Studio workflow

From reusable design system to finished slide document

All slide tools use the same suamuka.slides/1.0 contract as the visual editor. Every write is scoped to the OAuth user and validated before it is saved.

01 Discover
List folders, themes, layouts, components, and their stable references.
02 Build the library
Create or update custom design primitives before using them in projects.
03 Create a project
Start a new deck or duplicate an existing project with fresh identifiers.
04 Upload images
Store project images, then attach their asset IDs to photo elements.
05 Edit precisely
Add, update, duplicate, delete, or reorder slides and their elements.
06 Review and export
Open the returned editor URL for visual review and ordered PNG export.

Image asset workflow

Upload once, then attach by asset ID

Send raw base64 or a data:image/...;base64,... value. Suamuka detects the real file type, stores it on the project's configured media disk, and returns a URL for the photo component. Server filesystem paths are never exposed.

1. Upload
Send JPEG, PNG, or WebP data and a file name.
2. Attach
Use the returned asset ID with one photo element ID.
3. Inspect
List assets to see URLs and every slide using each image.
4. Delete safely
Clear both src and assetId before deleting an image.

Upload request

{
  "project_id": "project-uuid",
  "image_base64": "data:image/png;base64,iVBOR...",
  "file_name": "launch-cover.png",
  "alt_text": "Phone showing the product dashboard"
}

Attach request

{
  "project_id": "project-uuid",
  "asset_id": "asset-uuid",
  "slide_id": "slide_uuid",
  "element_id": "element_uuid",
  "alt_text": "The launch dashboard on a phone"
}

The upload tool does not download arbitrary remote URLs. This prevents an agent from making the Suamuka server contact private or untrusted network locations. Download the image in the agent environment, encode it, then upload it.

Library definition shapes

Themes use exactly three colors. Components define reusable defaults. Layouts position component references on the 0–100 canvas.

{
  "theme": { "colors": ["#f4efe6", "#e26b3f", "#18201f"] },
  "component": {
    "type": "headline",
    "position": { "x": 8, "y": 31, "width": 84, "height": 28, "z": 2 },
    "props": { "text": "One clear idea", "fontFamily": "serif", "fontSize": 110, "align": "center" }
  },
  "layout": {
    "key": "statement",
    "description": "A focused statement slide",
    "elements": [{
      "componentRef": "component.headline.v1",
      "position": { "x": 8, "y": 31, "width": 84, "height": 28, "z": 2 }
    }]
  }
}

Focused vs. bulk edits

Focused tools return the complete updated project, so the next call can use the latest slide and element IDs. For many coordinated changes, get the document once and replace it atomically.

{
  "project_id": "project-uuid",
  "action": "add",
  "slide": {
    "layoutRef": "layout.statement.v1",
    "elements": [{
      "componentRef": "component.headline.v1",
      "props": { "text": "The next useful idea" }
    }]
  }
}

Element props also take optional style keys: color, fill, fontFamily, fontSize, align, opacity, rotation, shape, and more. list_slide_library_tool returns the full list as style_props. Unknown keys are dropped on save.

Reorder actions require every current ID exactly once. Positions use percentages: x, y, width, height, and integer z.