> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fimo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Fimo MCP reference

> Tools, access scopes, and work sessions exposed by the hosted Fimo MCP server.

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](/docs/ai/mcp.md).

Fimo's hosted MCP server lives at:

```text theme={null}
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:

1. `projects_create` creates the project, with the `nextjs` starter unless you ask for another framework.
2. `sessions_start` opens one work session on `main`.
3. `files_write_many` writes the site's files in one saved change.
4. `sessions_validate` checks the session. The client fixes reported issues in the same session and validates again.
5. `sessions_close` with `action: "merge"` applies the change, and `preview_open` returns a live Preview URL for `main`.
6. 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](/docs/studio/integrations.md) 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](/docs/studio/integrations.md#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.

> [!NOTE]
>
> 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.

**1. 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`.

**2. 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.

**3. 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.

**4. 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.

```json theme={null}
{ "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`:

```json theme={null}
{
  "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](/docs/ai/mcp.md)**
>
> Connect an AI app and build a site from a conversation.

> **[Apps](/docs/studio/integrations.md)**
>
> Give your sites tools from other services and MCP servers.

> **[CLI reference](/docs/reference/cli.md)**
>
> Work on the same projects from a terminal.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.