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.

If an account-level client needs a site that is not yet connected, call flax.sites.request_access with the exact site URL, show the returned approval link, and call flax.sites.list again after the owner approves it. Never construct the link or request credentials in chat.

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.

Create a new site

For a new site, use flax.sites.create. It returns a normal text link to /create-from-agent/, where the owner can choose a complete site starter, build from custom sections, or upload a flyer for AI analysis and a flyer-informed section setup. They then complete account creation, email verification, and publishing. This is a full-page flow, a dedicated Flax page. When the site is live, Flax shows a copyable continuation prompt with the new site URL so the owner can return to the agent for content, logo, and checklist help.

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.

Onboarding checklist

Use flax.onboarding.checklist to read the Flax-managed launch and growth checklist. The result includes live completion state, evidence, Flax links, a recommended next action, and an offer for the agent to help. The order is guidance only, and every task can be skipped when it is not relevant.

Agents can mark manual tasks complete or skipped. Site creation, custom-domain connection, and Google Search Console are verified from Flax state; Search Console is blocked on temporary *.flaxsites.com domains. The result includes public Bunny pull-zone/DNS details for the domain setup without exposing Bunny credentials. Use the returned Flax link or an owner-authorized browser session to complete the connection.

Create local SEO spoke pages

Use flax.seo.create_service_location_page to create a service page for a service area or physical location. It referencesmodel.serviceLocations.locations[] or model.locations.locations[], creating the location record first when needed, and stores the page in model.seo.pages[pageKey].

Supply unique, fact-based content.intro and content.contentBlocks. Flax can match or accept explicit review, article, and FAQ IDs and applies the existing linking fields so the spoke can surface local proof, articles, and FAQs. The tool returns the exact model paths, page URL path, links selected, and a pending owner-review draft; it never publishes directly.

Competitor analysis

The canonical local SEO result is flax.seo.get_monthly_report. It combines organic search, local-pack visibility, citations, citation gaps, trends, and actions from the saved monthly snapshot. The report is generated automatically for eligible Managed sites and is read-only from MCP.

Use flax.seo.site_snapshot for a compact pages and headings inventory based on the published model.json. Each page lists its URL, slug, H1, and content-block headings with the model paths to edit them; section pages take a custom slug at ui.sections[i].slug, and renamed URLs redirect automatically on the next publish. Use flax.seo.competitor_snapshot to crawl the genuine organic and local-pack competitors selected by the monthly report from their homepages through same-site links to depth 3. The crawl stores reusable page, heading, and evidence snapshots; pass the returned job IDs to the same tool to check completion.

Use flax.seo.check_nap_citations for the connected Flax site's name, address, phone, citation coverage, and competitor-only gaps. It reuses monthly citation history, queues only missing or explicitly refreshed provider checks, and never edits external directories. Older SERP-led competitor-analysis and generic crawl MCP tools are no longer part of the public catalog; agent-job reports such as sales and marketing reports are unaffected.

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.

The snapshot also includes configured aggregate review profiles underreviews.reviewSites, with exact paths and values for the source, score, review count, and public profile link. Save verified platform ratings there; they are separate from individual review quotes. Multiple Reviews UI sections can reuse this one shared model. To show a compact rating strip, use flax.sections.add with templateHint="reviews-score-banner".

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.

Choose the correct brand logo variant

Flax stores background-specific brand marks at businessInfo.logoLight and businessInfo.logoDark. The names describe the background, not the artwork colour: logoLight is for light or white backgrounds and is usually a dark logo, while logoDark is for dark, purple, or black backgrounds and is usually a white or light logo. businessInfo.logo is the fallback.

Before changing one, inspect the exact rendered section and its palette. A logo in a white header normally uses businessInfo.logoLight; a light logo in a dark footer normally uses businessInfo.logoDark. Do not use lightLogo or darkLogo, and do not replace both variants when the owner named only one location.

Header and footer are renderers, not owners of the brand logo. Do not search header.images or footer.images, use a numeric image position, or call section-image replacement tools for a brand-logo request. Use the section location only to determine its background, then update the matching global businessInfo field.

If the user has already attached the replacement or uploaded it through the connected Flax site, use its non-empty src and do not call flax.media.begin_upload again. Write only businessInfo.logoLight.src or businessInfo.logoDark.src; replacing the whole logo object can discard existing metadata. An ID, filename, or name without src is incomplete and must be rejected rather than creating a blank logo.

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. For a homepage section, use button type content with flax://content/<section-id>. For a generated page, use button type page with flax://page/<page-type>/<item-id> and an optional /<section-id>. 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.

Direct Flax editor links

Template and branding selection tools return direct links to the Flax editors. Show the returned editor link so the site owner can make the choice in Flax. The agent can then use the documented tools to prepare an owner-review draft.

Site creation also opens as a full-page Flax flow. Content changes stay drafts until the owner reviews and publishes them in Flax.

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.

For a section background pattern, use flax.sections.change_config with the returned background option and value null to clear the saved background field. A backgroundOpacity value of 0 suppresses all background output in the generated site.

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, and branding settings, including 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 a genuinely agent-generated image whose bytes are not already attached or stored in the site, follow the upload sequence in the recipe index with flax.media.begin_upload before submitting the model update. User-supplied or site-uploaded images bypass that raw upload flow and are passed unchanged to the next content or model-update tool. The recipe includes the required raw binary PUT example, the success attachment shape, and the HTTP error codes and recovery rules.

Keep the returned upload URL and headers together. If a raw PUT times out, retry the unchanged URL, headers, and bytes while the ticket is valid; Flax safely returns the existing attachment for an identical retry. For 403 invalid_ticket, request a fresh upload and use its complete URL/header bundle rather than rebuilding or mixing a ticket.

This generated-image upload is available to MCP clients such as ChatGPT. The built-in /agent chat does not generate image files, but owners can upload an image there or choose one from the Flax media library.

Storage, schedules, and notifications

Site-scoped 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. Site-scoped Hermes agents can also use flax.schedules.* for native recurring tasks and flax.workspace.notify_owner for concise scheduled-task notifications, and flax.notifications.send for explicit owner-requested email. Email is owner-scoped and accepts plain text with an optional same-origin action link; it does not accept arbitrary recipients or raw HTML. 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.