Skip to content
Genie logo Genie logo Genie - AI Workbench for FileMaker

Local MCP Bridge

Use Local MCP Bridge when you want an external editor or agent on the same Mac to work with Genie as a FileMaker-aware workbench.

This is the local agent handoff layer for Codex, Cursor, Claude Desktop, and other MCP-capable clients. It lets an agent inspect Genie-owned FileMaker context, call bounded tools, and hand supported work back to Genie without creating a hidden apply channel. Genie also includes an explicit beta setting for trusted clients that can automatically run Genie’s Create Script flow for supported script stages.

Local MCP has three jobs:

  • expose FileMaker metadata, script context, guides, and layout resources to trusted local clients
  • give agents safe read-only tools for schema, script evidence, calculation evaluation, and SELECT data checks
  • stage supported script, DATA, or copy-only layout work for user review through Genie-owned flows

What it does

Section titled “What it does”

When enabled, Genie exposes a local MCP server on 127.0.0.1 and a port you choose in Settings. Clients connect with a bearer token generated by Genie.

External clients can:

  • list open FileMaker files and inspect bounded file metadata with genie_files
  • read effective Generic/Project Personalization guidance with genie://context/project or the compatibility project_context reference
  • read live or attached script context with genie_scripts
  • fetch Script Schema, Script Catalog, step records, and function records through genie_scripts
  • inspect tables, fields, layouts, relationships, value lists, and metadata selections with genie_metadata
  • evaluate FileMaker calculations safely with genie_evaluate
  • run read-only SELECT previews or results with genie_query
  • stage one reviewed DATA request with genie_stage_data
  • compile copy-only layout objects with genie_stage_layout
  • review or delete staged Workbench items with genie_workbench

MCP tool calls normally do not apply changes to FileMaker. Workbench items remain user-controlled, and AGENT-generated script work in the Genie UI is promoted back into the normal CODE Preview/Copy/Apply card instead of becoming a separate apply path. If Automatically create scripts in FileMaker is enabled in Local MCP settings, supported successful script stages from authenticated local clients can immediately run the reviewed Create Script path. Existing scripts are never replaced; edit flows create a new version.

Local MCP settings with the beta automatic script creation option

Where to turn it on

Section titled “Where to turn it on”

Open Settings Guide and configure Local MCP Bridge.

You can control:

  • Enable Local MCP Bridge
  • Automatically create scripts in FileMaker (beta)
  • Port
  • Status
  • Setup guide
  • Copy snippet

The setup guide can show:

  • Codex (Streamable HTTP)
  • Claude Desktop (stdio bridge)
  • Cursor / generic JSON
  • Endpoint URL
  • Bearer token

The visible preview masks the token where appropriate. Copy actions use the real local token.

Local MCP Bridge settings showing the Codex Streamable HTTP setup guide

Beta: automatically create scripts in FileMaker

Section titled “Beta: automatically create scripts in FileMaker”

The beta Automatically create scripts in FileMaker setting is for trusted local automation only. When it is enabled, a connected MCP client with the current bearer token can submit supported script stages and have Genie immediately run the existing Create Script flow.

Important boundaries:

  • It works through Genie’s Create Script path; it is not a separate hidden mutation tool.
  • Existing scripts are never replaced. Script edits create a new version instead of overwriting the original.
  • Every authenticated local MCP client using the current token can use the beta while it is enabled.
  • Turn it off when you are not actively working with a trusted agent that should create scripts immediately.

Workbench still shows pending and submitted sections so you can inspect the handoff trail and warnings.

Optional Klai / BetterForms guidance

Section titled “Optional Klai / BetterForms guidance”

Settings also includes Advanced > Agent / MCP > Expose Klai hook guidance.

Turn this on when you want Genie AGENT and connected MCP clients to have more Klai / BetterForms knowledge for business-file hook work. The main guide is a compact router. Focused resources cover execution/return contracts, Helper Inbox evidence interpretation, async/Data API/cache/performance/PSOS work, and missing-context collection.

The Helper Inbox is treated as runtime flight-recorder evidence, while the business file remains the implementation authority. Helper traces and static Genie script inspection must be correlated. A present marker proves it was emitted; a missing marker does not prove that a calculated or unlogged script did not run.

This setting adds knowledge resources only. It does not add Klai-specific tools, change Genie’s general FileMaker capabilities, or widen staging, Workbench, Direct Script Creation BETA, Apply, or mutation behavior. Agents apply the guidance to evidence available through Genie’s existing tools and clearly state when exact Helper runtime evidence is missing.

After changing this capability, reconnect the MCP client so it refreshes its tool and guide index.

Section titled “Recommended agent workflow”

External agents should use the bridge in this order:

  1. Call genie_get_capabilities.
  2. Read relevant guides with genie_get_guides, or read genie://guides/* directly when the client exposes MCP resources.
  3. Use genie_files when the task depends on the active/open FileMaker file. activate only raises an already-open FileMaker window; it does not stage, apply, mutate data, or serve inactive-file script XML.
  4. Use genie_scripts action=get_context or genie://context/scripts for current script evidence.
  5. For script authoring, use genie_scripts action=get_schema, then targeted get_catalog, get_steps, or get_functions calls.
  6. Use genie_metadata for schema discovery and parse_selection when a staged script, DATA, or layout request references real FileMaker objects.
  7. Use genie_evaluate before trusting complex Let(), JSON parsing, ExecuteSQL, or custom-function calculations.
  8. Use genie_query only for actual read-only row data, not field lists or relationship discovery.
  9. Stage through genie_scripts, genie_stage_data, or genie_stage_layout only when the request fits those lanes.
  10. Review Workbench with genie_workbench. Use action: "delete" with an item job_id to discard an obsolete draft. Running or applying remains a user action in Genie, except for the separately documented opt-in Direct Script Creation BETA behavior.

Core resources

Section titled “Core resources”

Essential anchors:

  • genie://schemas/script-schema
  • genie://schemas/script-catalog
  • genie://schemas/layout-schema
  • genie://context/project
  • genie://context/scripts
  • genie://metadata/relationships
  • genie://metadata/relationship-graph
  • genie://metadata/selected
  • genie://metadata/all

genie://context/project includes the effective project name, description, enabled rules, naming conventions, reusable patterns, script template, and guidance_sources showing whether each inherited field came from Project or Generic Personalization. This guidance can shape names, comments, patterns, and script structure, but it never expands tool access, Workbench staging, Apply, Stage A/B scope, or mutation authority.

Important guide resources:

  • genie://guides/script-delta-editing
  • genie://guides/metadata-selection
  • genie://guides/stage-contract
  • genie://guides/relationships
  • genie://guides/layout-design
  • genie://guides/filemaker-guide-manifest
  • genie://guides/filemaker-behavior-core
  • genie://guides/filemaker-script-review
  • genie://guides/filemaker-script-debug
  • genie://guides/filemaker-data-behavior
  • genie://guides/what-not-to-stage

When the Klai pack is enabled:

  • genie://guides/klai-filemaker-business-hooks
  • genie://guides/klai-hook-execution-contract
  • genie://guides/klai-helper-inbox-diagnostics
  • genie://guides/klai-hook-async-data-cache-diagnostics
  • genie://guides/klai-hook-request-template
  • genie://guides/klai-resource-map

Layout-focused agents may also read:

  • genie://layout/schema
  • genie://layout/objects-dictionary
  • genie://layout/style-ast
  • genie://layout/stylesheet-contract
  • genie://layout/fm-attribute-model
  • genie://layout/design-to-fm-transform
  • genie://layout/asset-registry
  • genie://layout/roundtrip-fidelity
  • genie://layout/paste-survival
  • genie://layout/host-import-proof
  • genie://layout/visual-render-proof
  • genie://layout/completion-audit

Use genie_get_guides when a client exposes tools but not resources. It lists and returns the same guide content through normal tool calls.

Current tool surface

Section titled “Current tool surface”
ToolUse forBoundary
genie_get_capabilitiesCurrent MCP contract, routes, and tool boundaries.Call early.
genie_filesList open FileMaker files, get active file, fetch bounded named-file metadata, or activate an already-open file window.Activation is foreground UI only.
genie_scriptsScript context, active script lookup, bounded content, Script Schema, Script Catalog, steps, functions, validation, compile preview, and script staging.One scripts tool; normal authoring uses Script Schema.
genie_metadataTables, table occurrences, fields, layouts, relationships, value lists, targeted describe, and parse_selection.Do not use genie_query for schema discovery.
genie_get_guidesGuide/resource fallback for clients that do not expose MCP resources.Omit key to list guides.
genie_evaluateSide-effect-free FileMaker calculation checks.Use Let() mocks for runtime variables.
genie_queryRead-only SELECT data rows.SELECT only; not field/schema discovery.
genie_stage_dataOne reviewed DATA SQL/schema request.User confirms execution in Genie.
genie_stage_layoutCompile copy-only Layout Schema, Figma import, import JSON, or LayoutObjectList XML.Paste-only layout objects; no host layout apply.
genie_workbenchList, get, inspect status, or delete one staged item.delete needs the item job_id; Run/Apply stays in Genie UI.

What can be staged

Section titled “What can be staged”
LaneStage whenImportant limits
Script: newCreate one new FileMaker script.Use genie_scripts with Script Schema and result_type: "new_script". One script per stage call.
Script: editEdit a named script using exact live or attached content.Use genie_scripts action=get_content or genie://context/scripts; merge_ready is optional whole-script merge capability, not a staging gate. Do not ask for Add Selection, attachment, or opening the script merely to stage; select/open it only before Apply. Multiple independent drafts may target the same script, but must be reread/restaged after an earlier Apply changes their anchors.
DATAStage one supported FileMaker SQL data/schema request or migration plan.Use genie_stage_data; inspect metadata/relationships first for related-table work.
Layout objectsCompile copy-only layout objects.Use genie_stage_layout; paste manually in FileMaker Layout mode.
Raw XML (expert)Hand completed FileMaker XML into Genie for review.Normal script work should use Script Schema, not raw XML.

Some FileMaker work stays manual:

  • table occurrences
  • relationship graph edits
  • layout shells, parts, themes, and host-layout import/apply
  • privilege sets, accounts, and security objects
  • custom menus and other FileMaker UI administration

QUERY stays with genie_query outside Workbench. ASK/planning stays in the IDE or normal Genie chat.

Routing examples

Section titled “Routing examples”
User intentAgent should do
”Create a script that exports Customers as JSON.”Read guides/schema, resolve metadata, validate with genie_scripts, then stage or return a Genie AGENT script artifact depending on surface.
”Update the selected script to add logging before the API call.”Read exact script content with genie_scripts, stage the targeted delta_edit, and select/open the target only before Apply.
”Create two scripts: Export Customers and Export Orders.”Split into two separate script artifacts/stage calls.
”Create table Customers with Email and Status fields.”Inspect metadata, then stage one DATA request with genie_stage_data.
”Show me active customers.”Use genie_metadata for schema, then genie_query for read-only rows.
”Create a relationship graph and put a portal on the layout.”Inspect relationship metadata, then give manual FileMaker instructions. Do not stage graph edits.

IDE configuration

Section titled “IDE configuration”

Use the setup guide in Settings to copy the current snippet for your client. Current snippets identify the server as genie_filemaker.

For Codex, use Streamable HTTP in ~/.codex/config.toml:

[mcp_servers.genie_filemaker]
enabled = true
url = "http://127.0.0.1:3845/mcp"


[mcp_servers.genie_filemaker.http_headers]
Authorization = "Bearer <generated-token>"

For Cursor or generic MCP JSON clients, use:

{
  "mcpServers": {
    "genie_filemaker": {
      "url": "http://127.0.0.1:3845/mcp",
      "headers": {
        "Authorization": "Bearer <generated-token>"
      }
    }
  }
}

For Claude Desktop, use the Claude Desktop (stdio bridge) setup guide. Genie uses mcp-remote@latest as the local stdio bridge to the Streamable HTTP server:

{
  "mcpServers": {
    "genie_filemaker": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://127.0.0.1:3845/mcp",
        "--header",
        "Authorization:Bearer <generated-token>"
      ]
    }
  }
}

Failure expectations

Section titled “Failure expectations”

When Genie cannot answer or stage a Local MCP request, the response is usually a structured ok:false result rather than a transport crash.

The fix is usually to:

  • open or activate the correct FileMaker file
  • refresh or capture the right Script Workspace context
  • inspect metadata with genie_metadata
  • split bundled work into one supported lane at a time
  • do relationship, table occurrence, host-layout, or security work manually in FileMaker

Good uses

Section titled “Good uses”
  • keeping an IDE-side agent aligned with FileMaker metadata
  • reading script context without pasting broad XML into chat
  • validating FileMaker calculations before staging
  • checking relationships and field lists before DATA or script work
  • staging one reviewed script, DATA, or copy-only layout item
  • letting AGENT gather evidence through the same MCP tool contracts
Section titled “Related pages”