Fine Structure MCP server

Discovery for the media tools: the active image model and remaining image allowance, the video models this account may use with their per-second prices and prepaid wallet balance, and every valid slideshow style, template, and collection id. Call this before generate_image / generate_video / generate_slideshow instead of guessing enum values. Spends nothing.

Poll one video job by id. Refreshes from the provider while it is still rendering and returns video_url once status is 'completed'. Spends nothing.

List this account's own video jobs, newest first. Spends nothing.

List this account's slideshows, newest first, without slide bodies. Spends nothing.

Price a video render before generating it. Returns the duration, resolution, and the exact charge in USD against the prepaid video wallet. Spends nothing.

Render the images for a slideshow whose script was already written and approved. Charges 1 platform credit per slide, runs in the background, and returns immediately - poll get_slideshow until status is 'ready'.

Fetch one slideshow: its script, render status (script_ready, rendering, ready, render_failed), and the image URL of every rendered slide. Spends nothing.

Agency mode only. Create or update a client record for an account-level agent. This does not create a verified Fine Structure user account and does not transfer ownership.

Agency mode only. Create a client claim link for an existing app owned by the agent. The client must log in with the invited email before ownership transfers.

Update an existing application with a new prompt. The AI modifies the app based on your instructions. Creates a Saved Version before the update. Returns a job_id - poll get_job_status to track progress.

Publish an app - freeze current state and make it live at a URL. Also configures whether the public URL is open, app-login gated, private, or inferred from the app.

Create/insert records in one app entity. Executes directly for the authenticated app owner and returns the created record ids.

Update exact records. Select explicit record_ids or exact-match filters and provide shared changes, or provide per-record updates. Executes directly for the authenticated app owner; expected_count aborts the write on a mismatch.

Update a native A/B test, including active state, variants, traffic, and conversion goal. Creates a Saved Version before the change.

Create a native Fine Structure A/B test between existing app pages. Use update_app first if a variant page still needs to be generated. Creates a Saved Version before the change.

Create an autonomous AI agent on the user's Fine Structure account: a standing worker, not a chat session. It gets the platform's default safe tool policy and its own email address, it can read and write the app database, and once the owner phone is verified (see get_agent_whatsapp) it can message its owner on WhatsApp and by email through the platform system channels. Pair it with schedule_agent_task for recurring work such as following up new leads on WhatsApp each morning, watching an app for runtime errors, or sending a weekly summary. Messaging anyone other than the verified owner requires a channel the owner connects in the Fine Structure Studio.

Get views, unique visitors, conversions, and conversion rates for an A/B test.

Agency mode only. List client records and app handoff status for the authenticated agent.

Rename or move one app source file atomically. Internally stages an upsert at new_path and a delete at old_path, validates the resulting app state, and creates a Saved Version before applying.

Admin only. Create a scheduled email sequence using fixed dates or day offsets. Each generated email keeps mandatory unsubscribe.

Create an app-scoped email sequence using fixed dates or day offsets between emails.

Agency mode only. Inspect one handoff status without exposing the raw claim token.

Compatibility endpoint for full Saved Version restore. MCP cannot execute this operation because it can replace database records without the dedicated in-chat approval flow. Use list_saved_versions and compare_current_to_version for read-only inspection, then ask the authenticated app owner to restore through the Fine Structure UI.

Return server-side preview context: URLs, persisted runtime/network errors, static clickable candidates, pages, and explicit live-browser availability.

Create an app-scoped broadcast to contacts synced from that generated app, optionally scheduled or sent now.

Attach or replace the app custom domain through the same Fine Structure Studio custom-domain flow. Returns exact DNS verification and routing records for the user to configure at their DNS provider.

Query app data records for one entity with optional exact-match filters.

Create a scheduled task for one of the user's agents. Supported schedule types: once (run_at ISO local time + timezone), interval (interval_minutes 5-1440), hourly, daily (time HH:MM + timezone), weekly (time + timezone + days_of_week 0=Sunday..6), cron (5-field expression + timezone), manual (only runs on demand). Returns the normalized schedule and the computed next_run_at so you can read the fire time back to the user in their timezone.

Disconnect the owner's WhatsApp route from a platform number. Removes only this account's route; other accounts sharing the number keep theirs.

Read the WhatsApp state of the connected account: whether the owner's phone is verified, which platform numbers they can connect, and which conversations already route to which agent. Call this first whenever the user asks to talk to an agent on WhatsApp, and repeat its next_step to them.

Send a 6-digit code over WhatsApp to the ACCOUNT OWNER's own phone. This is the one-time ownership proof required before a platform number can be connected, and it also unlocks agents messaging the owner. Ask the user for their own WhatsApp number first and send only to that. No WhatsApp Business account is involved.

Confirm the 6-digit code the owner received on WhatsApp from start_owner_phone_verification. On success the owner is verified: agents can message them, and platform numbers become connectable.

Connect a platform WhatsApp number to one of the account's agents, so the owner can message that number and reach that agent. Requires the owner to be verified first. Take phone_number_id from get_agent_whatsapp. A number already used by another account is still valid to connect: it answers only this owner's verified phone.

Generate an AI video from a text prompt. Submits the render and returns a job_id immediately - poll get_video_status until it completes. Spends the account's prepaid video-credit wallet (NOT platform credits); pass max_charge_usd to cap how much a single call may spend. Video generation may be invitation-gated.

Get app overview: files, published state, URL, active jobs.

List an app's platform path, subdomain, and configured custom domain with verification, SSL, primary-domain, redirect, publish, and login-gating status.

Set which app host should be treated as primary for generated links and custom-domain redirects.

Return the exact DNS records and instructions required to verify and route the app custom domain.

Remove the configured custom domain from the app and clean up the platform-side hostname registration when possible.

Check Fine Structure custom-domain verification and SSL status for the configured custom domain, then save the latest status.

List applications owned by the authenticated user, newest activity first. Returns up to `limit` apps per call plus the total count; page with `offset` when the account has more.

Get the file tree for an app with paths and byte sizes.

Read one source file from an app's virtual filesystem. Paths follow the Fine Structure app file API, documented at https://finestructure.ai/api/mcp/docs.

Get all entity (data model) schemas for an app, with record counts. Each entity has fields, types, and relationships.

List restorable Saved Versions for an app, including versions created by MCP writes.

Get all pages in an app with their file paths and sizes.

Get recent runtime errors for an app (last 20). Useful for diagnosing issues before updating.

Return editor preview and published/public URLs for an app.

Create a staged file change set. Add multiple file changes, validate them as one app state, then apply atomically.

Discard a pending staged change set without changing app files.

Validate current app files plus staged change set files before applying.

Apply a staged change set to the app. Creates a Saved Version before applying. Blocks on validation errors unless force=true.

Run deterministic app checks: syntax, imports, routes/pages, entity schemas, missing entities, and recorded runtime errors.

List generated-app runtime users/members for an app. This is separate from Studio project collaborators.

Remove a generated-app runtime member.

Read recent server-side security audit events for an app.

Compare the current app files to a Saved Version and return compact per-file diffs.

List secret key names for an app. Secret values are never returned.

Store safe non-secret integration metadata for an app. Use set_secret for API keys/tokens.

Create or update one encrypted app secret. The secret value is never returned.

Replace or shallow-merge an existing entity schema file. Creates a Saved Version before writing.

List the platform A/B tests configured for an app.

Validate entity relationship metadata and *_id references against existing entity schemas.

Delete one app secret by key.

Set relationship/index metadata on an entity schema. This stores metadata in the schema file; DB index creation is automatic where supported by the platform.

List supported integrations and safe connected integration metadata for an app. Tokens/secrets are never returned.

Return a machine-readable Fine Structure / FSe2 guide for AI agents. Call this at the start of an MCP session to learn app files, entities, safe edit workflows, validation, publishing, A/B testing, secrets, and platform rules.

Provision a generated-app runtime member with a role. This does not create a Studio collaborator, and the owner role cannot be assigned. password is required: ask the account owner which password the member should get. This tool never generates one, because a generated password would come back in the result and that is a live credential in the conversation transcript.

Admin only. Inspect the isolated Email Marketing module: enabled state, sender settings, templates, sequences, variable triggers, and recent campaign status.

Inspect app-scoped Email Marketing for one generated app: settings, contacts, campaigns, event triggers, and recent events.

Admin only. Manually fire variable-transition email rules for one user. Useful for MCP/agent workflows and tests.

Sync an app entity table into app-scoped Email Marketing contacts. Records without a valid email are skipped.

Create an app-scoped email rule that sends when an app event is recorded, for example entity_created or Customer.created.

Record an app event and send matching app-scoped Email Marketing triggers.

Create an app-scoped automation workflow with email, wait, condition, split, and goal steps.

Read app-scoped Email Marketing reporting: delivery counts, open/click rates, and recent tracking events.

Create an app-scoped saved audience segment using field, tag, and behavior filters.

Read provider readiness, bounce/complaint rates, suppression reasons, and recent deliverability risk events.

Suppress an app contact email after a bounce, complaint, manual block, provider block, or unsubscribe.

Process due app-scoped automation workflow runs and email queue jobs with locks, retries, and suppression checks.

Inspect app-scoped Email Marketing queue jobs and per-status counts.

Return editor, preview, published path, subdomain, and custom-domain links plus whether each works for anonymous visitors, app users, or Studio users based on publish and auth settings.

Update a generated-app runtime member role. This cannot assign owner and cannot change the Fine Structure account owner.

Configure custom-domain redirect policy: primary domain, optional www/root redirect, and HTTPS enforcement.

Delete a native A/B test from an app. Creates a Saved Version before the change.

Read a contact profile with email delivery, tracking, app-event, workflow, suppression, and unsubscribe timeline.

Poll the status of an async generation job. Use this after create_app or update_app to know when the job is done. Returns status ('running' or 'done'), progress events, and result summary when complete.

Create or replace one file in an app's virtual filesystem. Creates a Saved Version before changing content. Paths and file model follow the Fine Structure app file API, documented at https://finestructure.ai/api/mcp/docs.

Compatibility tool that updates one record by ID. Executes directly for the authenticated app owner.

Configure isolated Email Marketing settings for a generated app. Can be used by Studio/chat agents.

Patch one file by replacing exact text. Safer than full overwrite for targeted edits. Creates a Saved Version before changing content. Paths follow the Fine Structure app file API, documented at https://finestructure.ai/api/mcp/docs.

Create or update server-side read/write role policy for an app entity.

Admin only. Create a filtered broadcast campaign, optionally scheduled or sent now.

Generate one marketing image (ad creative, thumbnail, hero, social graphic) and return a public URL. Free plans burn one of their monthly free images; paid plans spend 1 platform credit. Optionally pass a reference image to keep a person, product, place, or brand consistent.

Admin only. Configure global Email Marketing sender details and module enabled state. Unsubscribe footer remains mandatory.

Admin only. Update an automatic Email Marketing template, such as user_joined welcome email. The unsubscribe block is still appended by the server.

Admin only. Create an email rule that sends when a named variable changes from one value to another. Empty from_value/to_value acts as wildcard.

Write a TikTok/Instagram-style slideshow: hook, per-slide copy, caption, and hashtags, in any supported language. Costs 1 platform credit and returns the script for review. Set render_images=true to start image rendering right away (1 extra credit per slide), then poll get_slideshow until status is 'ready'. Pass slide_images to composite the slides on the account's own photos (Instagram carousel mode) and output_format for 9:16, 4:5, or 1:1 geometry. Call list_media_capabilities for the valid style, template, and collection ids.

Traffic analytics for an app's published site over a chosen window: total views, unique visitors, daily series, top pages, top referrer domains and device split.

Stage one file upsert or delete inside a change set. Does not modify the live app until apply_change_set. Paths follow the Fine Structure app file API, documented at https://finestructure.ai/api/mcp/docs.

Compare two Saved Versions and return per-file additions, removals, modifications, and compact diffs.

List the AI agents on the user's account with id, name, role, status and FineMail address.

List scheduled tasks for one agent (or the whole account), including schedule, status and next_run_at.

Deep introspection of an app: entities, pages, settings, integrations, environment variables, and file structure. Use this to understand what an app contains before updating it.

Delete exact records by ID or exact-match filters. Executes directly for the authenticated app owner; pass expected_count as a safety check to abort on a mismatch.

Create or update a server-owned route policy for a generated app route.

Create an entity schema file in entities/<Entity>.json. Creates a Saved Version before writing.

Create a new application from a natural language prompt. The AI generates a complete web app with pages, components, styling, and data models. Returns a job_id - poll get_job_status to track progress. When the job is done, the app is ready.

Agency mode only. Create a new app owned by the agent, start generation, and create a claim link for the client. Ownership transfers only when the invited client logs in with the same email and accepts the claim link.

Return the recommended MCP tool sequence for a task type. Use this before creating apps, editing files, seeding data, publishing, setting up A/B tests, restoring versions, or configuring secrets/integrations.

Return SSL/certificate status and pending certificate validation DNS records for the app custom domain.

Compatibility tool for starter-record creation. Inserts directly for the authenticated app owner; by default it only seeds an empty entity (skip_if_not_empty).

Read several source files from an app's virtual filesystem. Paths follow the Fine Structure app file API, documented at https://finestructure.ai/api/mcp/docs.

Return safe security context for one owned app: owner id/email, Studio collaborators, generated-app members, route policies, entity policies, and recent security audit entries. Does not return secrets and does not grant access to other apps.

Restore one file from a Saved Version instead of restoring the entire app. Creates a Saved Version before changing the file. Paths follow the Fine Structure app file API, documented at https://finestructure.ai/api/mcp/docs.