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.
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.
create_slide_project_tool	Create a validated slide project from reusable library references.
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.
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.
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://suamuka.com/mcp/suamuka",
  "auth": "oauth"
}

Operational notes

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" }
  },
  "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" }
    }]
  }
}

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