Fimo MCP reference

This page is for developers building or debugging an MCP client. To connect ChatGPT or Claude and build a site, follow Build your site from ChatGPT or Claude. Fimo’s hosted MCP server lives at:

https://api.fimo.ai/api/mcp

A compatible remote MCP client opens Fimo sign-in and asks you to approve access. The tools the client sees depend on the access you grant, and every call still goes through your existing project permissions.

Typical flow

A client can take a site from an empty conversation to a live URL:

projects_create creates the project, with the nextjs starter unless you ask for another framework.
sessions_start opens one work session on main.
files_write_many writes the site’s files in one saved change.
sessions_validate checks the session. The client fixes reported issues in the same session and validates again.
sessions_close with action: "merge" applies the change, and preview_open returns a live Preview URL for main.
When you ask to publish, publications_publish publishes the site and waits until it is live, then returns its URL.

Clients that support form input requests also get a Fimo form. Before projects_create makes a site, a short form asks for its name, purpose, pages, look, current website and framework, and the assistant builds from those answers. Other clients ask these questions in the conversation. Clients that support form input requests show a confirmation from Fimo before publications_publish makes a site live, before projects_delete deletes one, and before projects_invite invites someone. Declining leaves the site unchanged. Turn off Ask before publishing in the ChatGPT app’s settings to publish without the confirmation. Other clients ask you in the conversation instead.

Tools

Hosted Fimo connections list the tools a chat needs to build, edit, publish, and run a site. Each one is named <domain>_<action> and carries its input and output schemas, so the client calls it directly.

Use	Tools
Find and create sites	`organizations_list`, `projects_list`, `projects_create`, `projects_delete`
Change code	`sessions_start`, `sessions_get`, `sessions_list`, `sessions_changes`, `sessions_validate`, `sessions_run_operation`, `sessions_close`, `sessions_conflicts`, `sessions_resolve`, `files_read`, `files_read_many`, `files_glob`, `files_grep`, `files_write_many`, `files_edit`, `files_delete`
See it running	`preview_open`, `sandbox_logs`
Publish	`publications_publish`, `publications_list`, `publications_logs`
Edit content	`schemas_list`, `schemas_get`, `schemas_create`, `schemas_create_many`, `schemas_update`, `schemas_delete`, `entries_list`, `entries_get`, `entries_create`, `entries_create_many`, `entries_update`, `entries_delete`, `singles_get`, `singles_update`, `labels_list`, `labels_set`, `labels_set_many`
Forms	`forms_get`, `forms_create`, `forms_update`, `forms_list_submissions`
Creation standards	`skills_get`, `call_status`
Media	`assets_list`, `assets_upload_from_url`, `generation_estimate_task`, `assets_generate`
Languages	`locales_list`, `locales_add`, `locales_set_default`
Address, domains, and team	`domains_rename_subdomain`, `domains_list`, `domains_add`, `projects_invite`
Results and limits	`analytics_pageviews`, `billing_credits`
Connected integrations	`integrations_list`, `integrations_tools`, `integrations_guide`, `integrations_run`, `integrations_write`
Undo	`history_list`, `history_restore`
Support	`support_report`

The connection lists only the tools covered by the OAuth scopes you approved:

Scope	Adds
`read`	Reads across projects, content, media, forms, publications, and analytics.
`write`	Creating and deleting sites, content, domain, and team changes, undo, and publishing.
`code`	Work sessions, file and schema changes, and URL asset imports.

Fimo still checks project permissions, tenant isolation, and every tool’s input and output on each call. Apps turned on for a site, such as Search Console or Semrush, go through five generic tools rather than one tool per app action: integrations_tools finds an app’s tools by what you need and returns the start of what each does, and returns one tool’s input schema when asked for it by its key, integrations_guide explains when to use them, integrations_run runs tools that read, and integrations_write runs tools that change the outside service. integrations_write needs the write scope, and a change made through it waits for a person unless the tool is always allowed on the site: it answers approval_required with a link to Studio. Someone allows the change there and gets a one-time code; paste it into the conversation, and the assistant calls integrations_write again with that approval. The code works once, for that exact change, within the hour. Actions that cost money ask every time. See Changes need a yes. The hosted MCP uses apps but does not connect them: an organization admin connects apps in Studio. Slow tools, such as creating a site, starting or closing a work session, validating, and publishing, answer pending with a callId after about 12 seconds and keep working. call_status with that callId waits for the work and returns its result; it never starts or repeats the work. Calling the same tool again with the same input while it runs also joins it instead of repeating it. The assistant makes requested changes itself. In ChatGPT, open Site preview from the conversation’s side panel to watch the site update after each change, and approve or discard changes there when automatic merging is off. The panel and the preview card show whether the site is live, and they load a fresh preview when you come back to an older conversation. Results meant for you, such as publications_publish, show as a small card in the conversation. view_sites, view_content, view_preview, view_images and view_changes show cards when you ask to see something, and edit_content opens an editor when you want to edit a whole entry yourself. The full Fimo app opens from the ChatGPT sidebar or a conversation’s side panel. The app also adds @ mentions for your sites and a settings page for how the assistant builds and publishes. The server instructions carry Fimo’s site-building rules. skills_get serves the detail: the fimo-site references for design, content schemas, labels, forms, media, SEO and each framework, and fimo-site-migration for rebuilding an existing website. Branches, schedules, webhooks, secrets, environments, and domain purchases are not part of the hosted MCP. Use Studio or the Fimo CLI for them. Coding agents working beside a checkout should use the CLI and installed skills.

Use hosted work sessions

Changes to files, schemas, or dependencies happen in a work session: an isolated draft with its own sandbox. main stays unchanged until the session merges.

Work sessions require the code access scope. Read-only access is selected by default. If a connector was connected before work sessions were available, reconnect it and approve the code scope.

Start a session

Call sessions_start with the project, a short name and goal, and optionally a target Branch. Save the returned sessionId and expiresAt.

Make changes

Pass sessionId to files_write_many, files_edit, files_delete, schemas_create, schemas_update, or schemas_delete; a schema change writes its file, registers it and regenerates its client in one call. Use assets_upload_from_url to import a public URL into the draft’s Media Library. Each change is saved before the tool returns.

Review and validate

Pass the same sessionId to files_read, files_glob, or files_grep to see the session’s own files. Call sessions_changes to review the change set, then sessions_validate, which also runs the project’s typecheck script. Run the project’s own checks with sessions_run_operation and operation: "typecheck" or "lint"; they report their output without saving. Fix reported issues in the same session and check again.

Finish the session

Call sessions_close with action: "merge" to apply the changes, or action: "discard" to remove them. Add a description of why the change was made; it becomes the body of the merge commit. If a merge conflicts, nothing is written to main yet: read the conflicts with sessions_conflicts, then send a choice for each one with sessions_resolve to finish the merge. Each code conflict lists targetCommits, the commits on main that changed the file since the session started, with their message and author, so you know which changes to keep.

The response’s preview link is optional. A cold preview can return null without failing the operation; call sessions_get later rather than repeating an edit. Sessions expire 30 days after their last successful change. An expired session cannot be resumed; start a new one. files_read and files_glob take either branch or sessionId next to projectId, never both. A session read answers from the session’s last saved change, so a file you just wrote is readable there while main still shows the old content. assets_upload_from_url accepts a public HTTP or HTTPS URL up to 50 MiB. Fimo blocks private-network destinations, and the asset reaches main only when the session merges.

Edit content

Reads and content changes do not need a session. Entry and Single tools take projectId and branch, and keep the same project permissions as Studio. Entry, asset, and form-submission lists return { items, nextCursor, total }. Pass limit, then send a non-null nextCursor back as cursor with the same filters. Stop when nextCursor is null. Treat cursors as opaque.

{ "projectId": "project-id", "branch": "main", "typeName": "Article", "limit": 20, "cursor": null }

Check what is published and what is running

Question	Tool
What has been published, most recent first?	`publications_list`
Why did that publication fail to build?	`publications_logs`
What did the install and dev server print on this Branch?	`sandbox_logs`

Logs answer with a status rather than an error when there is nothing to read. Reading logs never starts a sandbox, which keeps the evidence of a failed deploy intact. billing_credits takes projectId and returns the same balance as fimo credits. Buying credits or changing a subscription stays in Studio. analytics_pageviews returns headline metrics, a time series, top breakdowns, and annotations for a preset or custom range, defaulting to the published site. To undo a change, find it with history_list and restore the version before it with history_restore.

Contact Fimo support

Ask your MCP client to contact Fimo support only when you want to send a report. The client submits the exact approved message with support_report:

{
  "message": "Publishing fails after validation.",
  "projectId": "project-id",
  "branch": "main"
}

message is required and can contain up to 20,000 characters. projectId is optional, but a branch requires one.

What’s next

ChatGPT and Claude guide

Connect an AI app and build a site from a conversation.

Apps

Give your sites tools from other services and MCP servers.

CLI reference

Work on the same projects from a terminal.

Start

Build your site

Preview and launch

Agents and automation

Work with your team

Migrate an existing site

Reference

Fimo MCP reference

Typical flow

Tools

Use hosted work sessions

Edit content

Check what is published and what is running

Contact Fimo support

What’s next

ChatGPT and Claude guide

Apps

CLI reference

​Typical flow

​Tools

​Use hosted work sessions

​Edit content

​Check what is published and what is running

​Contact Fimo support

​What’s next

ChatGPT and Claude guide

Apps

CLI reference

Typical flow

Tools

Use hosted work sessions

Edit content

Check what is published and what is running

Contact Fimo support

What’s next