Connect an AI agent

Looking for client profiles and copy-ready prompts? Visit the Flax agent hub. The machine-readable prompt recipes are also linked from the public discovery document.

Start with site-scoped discovery

When a user names a website, inspect that exact origin first. Fetch https://that-site.example/.well-known/mcp.json and use the advertised MCP URL. The generated document points to a site-scoped Flax Agent API route containing that site's ID. Follow its OAuth resource metadata challenge. Do not assume a connector or replace a named site with a global endpoint.

For account-level Flax administration without a named site, use https://agents.flaxsites.com/mcp. The account discovery document at https://flaxsites.com/.well-known/flax-agent.json lists the API, schemas, and preview URL.

How authorization works

1. The MCP client connects to Flax and receives an OAuth challenge.
2. It creates a one-time authorization link using its own redirect URL, state, and PKCE challenge.
3. The client shows that link as Connect Flax; the site owner opens it in their own browser.
4. The owner signs in, reviews access to the requested site, and approves or denies it. Account-level requests require an explicit site choice.
5. The MCP client receives the OAuth callback and can resume its connection.

The consent page is part of an active authorization request. Do not link directly to it or reuse an authorization URL: its state and PKCE values are specific to one client session.

What agents can do

Authorized third-party agents can read the requested site and propose allowed text changes. Changes are drafted first, so the owner can preview and approve them before deployment. Owner-authorized OAuth sessions can also preview and, after explicit confirmation, manage the site subscription with the billing tools: upgrades, downgrades, period-end cancellation, and refunds within the refund window. The managed Flax agent cannot perform billing mutations; direct the owner to Site login → Settings → Subscription instead. Agents cannot access site publishing credentials or other infrastructure credentials.

Competitor analysis

Site-scoped agents and MCP clients can use flax.research.request_competitor_analysis to queue a first-page SERP analysis for one or more keywords and locations. The service stores the completed brief and structured report in the site's private stable storage, where flax.research.list_competitor_analyses and flax.research.read_competitor_analysis can retrieve them later. Agents should check for a current stored report before starting a new request because provider usage may incur cost.

Homepage snapshot and read order

Use flax.site.get_snapshot first for homepage audits and broad read-led reviews. It returns a complete structural homepage inventory, keeps the rendered section order and effective visibility, links canonical content to ui.sections, and reports missing or orphaned content without returning detailed body copy.

For broad site reads, continue in this order: flax.content.get_active_section for what one current section template visibly renders, flax.content.get_type for its full canonical CMS root,flax.site.scan_model for known text, IDs, or paths,flax.site.get_model with view="compact" only when those reads are insufficient, and view="full" only for explicit structural or template investigations, or validated update workflows. For a known shared value such as a telephone number, use flax.site.scan_model as the targeted lookup and reuse its returned paths.

Find model values before editing

Use flax.site.scan_model when you need to locate a value without downloading the full model. Pass an array of queries and use the default indexOf matching for simple lookups, orregex for a pattern. The compact result includes the model path, matched value, and queries that matched. SetincludeContext only when you need the canonical sub-model and its matching model.ui.sections[] record as well.

This is useful for shared values such as phone numbers: scan first, then use the returned paths in a validated model-update plan. The scanner is read-only and limits query and result sizes to keep the response focused.

Read what a section actually renders

Use flax.content.get_active_section with an exact section ID before discussing its visible title, introduction, images, or content blocks. Flax compiles the current template and variants and returns rendered content separately from hidden CMS inventory. Hidden paths remain editable, but they must not be described as visible.

Read linked content by type

Use flax.content.get_type when you need one canonical content root together with the model.ui.sections entries that render it. For example, services returns one item containing model.services and every matching active services section. Keyed roots such as articles, faqs, and general return one item per key, with the model path and linked section kept together.

Linked sections are active sections by default. Set includeDisabled to true only when you need to inspect content that is currently not rendered.

Flax internal links and efficient reads

Flax internal links are resolved by the site compiler. Use flax://content/<section-id> to jump to a homepage section, or flax://page/<page-type>/<item-id> with an optional /<section-id> to target a generated page. Use the exact section and record IDs returned by the model; do not invent slugs, use a bare hash, or guess a public URL.

Choose the narrowest read within the order above. The full model is an explicit fallback for structural or template work, not the default site-read tool. Pass parameters in the documented shape, such as a queries array, and reuse returned paths and IDs.

Agent-initiated template choices

When a user asks to change a section without choosing an exact style, call flax.interactions.request_section_template_selection. It pauses the current turn with an awaiting_user_selectioninteraction. The /agent chat renders the full-width carousel and resumes through a continuation callback after the user chooses a template. Then call flax.sections.propose_template_change with the exact selection; it creates the owner-review draft and never publishes.

Interactive MCP Apps UI

MCP clients that support the io.modelcontextprotocol/ui extension can render Flax's visual choices as sandboxed ui:// resources. Advertised resources include the section-template, section-palette, and whole-site theme pickers. A compatible client reads the resource from resources/read and follows the tool's _meta.ui.resourceUri link.

This is optional and backwards-compatible. Hosts without MCP Apps support continue to receive the normal structured result and text fallback; the first-party /agent chat continues to render its native picker and keeps owner-review drafts separate from publish actions.

Read, validate, and draft model changes

Use flax.site.get_model with view="full" only when an explicit structural or template investigation, or a validated update workflow, requires the complete model. Draft and validation responses include freshness data, so a separate model-hash read is not needed. After locating the exact paths, validate a schema-drivenModelUpdatePlan with flax.drafts.validate_model_updateand create the owner-review draft withflax.drafts.propose_model_update. The public SiteDataModel schema and model recipes describe the canonical data and section relationships.

The model tool also supports view="compact", which returns a flat entries array of visible text with IDs, media, UI styles, and internal settings omitted. Add includeI18n to include translation values or includeArticlesDetails to include inline article body text. Use view="compact_article" with an articleSectionId and articleId when one article needs a focused text-only scan. Detached article bodies are reported as unavailable to the endpoint.

When the interactive /agent section picker supplies an exact header template, use flax.sections.propose_template_change with the selected template and preset. It applies the registered /templates/header settings, keeps current header content and navigation where possible, reuses model images first, and uses media-library images only as a fallback. The result is always a pending owner-review draft.

Visual choices

Use the visual choices in the /agent chat for section templates, section colours, branding presets, and whole-site themes. The picker uses the registered Flax catalog and prepares a pending review draft when the owner applies a choice. Agents should open the relevant picker rather than reproduce visual catalog data in prose.

Articles and image uploads

Use flax.content.upsert_article for normal article creation or updates. The article recipe explains the optional inline body copy and supported rich text fields. Articles may also use only images or other supported article fields. For agent-local images, follow the upload sequence in the recipe index with flax.media.begin_upload before submitting the model update.

Storage, schedules, and notifications

Site-scoped Hermes agents use flax.documents.save to save a completed report as Markdown and update its Documents index in one call. They can use flax.storage.* for lower-level private durable work, flax.schedules.* for native recurring tasks, and flax.workspace.notify_owner for concise scheduled-task notifications. Storage is private agent workspace data, not public site content, and scheduled tasks cannot publish changes.

Analytics and integrations

flax.analytics.get_insights andflax.analytics.get_search_performance are available to every site-scoped agent. They return aggregate Flax Stats, Google Search Console data when connected, and Ahrefs Domain Rating when a custom domain is available. Domain, Google Search Console, and Stripe tools return owner-authorized actions; they do not complete DNS or OAuth flows for the owner.

Subscription tools require the site owner's OAuth session. Plan changes return a preview first; the agent must receive explicit confirmation before applying an upgrade or downgrade. Tier downgrades take effect immediately with a pro-rata credit for unused time, even outside the refund window. Cancellation defaults to the end of the billing period, while refunds cancel immediately and are limited to the current refund window.

Drafts and approval

Draft tools return a preview URL and never publish directly.flax.drafts.get_change retrieves a pending agent draft, while approval and deployment remain an owner-controlled Flax action.

Help and safety

If your MCP client asks for a Flax password, a magic code, or an access token in chat, stop the flow and use its Connect Flax authorization link instead. For help, email support@flaxsites.com.