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 computer to work with Genie as a FileMaker-aware workbench.

Local MCP Bridge requires Coding Access. Embedded AGENT keeps its Free read-only capabilities and confirmed existing-script run without enabling the external server.

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.

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 fm_session
  • read effective Generic/Project Personalization guidance with genie://context/project or the compatibility project_context reference
  • read live or attached script context with fm_read
  • discover Script Schema, guides, step records, and function records through fm_search
  • inspect tables, fields, layouts, relationships, value lists, and metadata selections with fm_read
  • evaluate FileMaker calculations safely with fm_evaluate
  • run read-only SELECT previews or results with fm_query
  • stage one reviewed DATA request with fm_stage
  • compile copy-only layout objects with fm_stage
  • inspect staged Workbench items, stage atomic ChangeSets, and verify an Apply receipt with fm_workbench
  • request one exact existing script run with fm_run, always behind a fresh native Run Script / Cancel confirmation

MCP tool calls do not Apply changes to FileMaker or Execute DATA directly. fm_run action:start is the narrow exception for an existing script: every start pauses for a fresh confirmation inside Genie, even if the MCP client remembers tool approval. Workbench items remain user-controlled, and AGENT-generated script work in the Genie UI is promoted into the normal native Preview/Copy/Create/Apply card instead of becoming a separate apply path. The former Automatically create scripts in FileMaker beta is shelved and no longer available.

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
  • Privacy mode
  • 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

Local MCP Privacy Mode

Section titled “Local MCP Privacy Mode”

Use Settings > Local MCP > Privacy mode when connected MCP clients should see only an explicit live FileMaker scope.

Local MCP Privacy Mode setting beneath the Local MCP Bridge control

When enabled:

  • the current Metadata Explorer selection becomes the native allowlist
  • an empty selection fails closed for live FileMaker tools and context
  • selecting a table does not automatically expose all its fields
  • Query and every Evaluate request require a fresh native confirmation
  • broad live resources, Web access, and report_issue are unavailable

Local MCP Privacy Mode is separate from the green Chat Privacy shield. Each controls its own channel, and enabling privacy does not overwrite the saved Product issue reports preference.

Optional Klai / BetterForms integration

Section titled “Optional Klai / BetterForms integration”

Settings also includes Advanced > Agent / MCP > Enable Klai Integration. This setting is independent of whether Local MCP is running.

Turn this on to show Genie’s Klai hook-set and Custom Function tools and to give Genie AGENT and connected MCP clients 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.

The MCP guidance exposed by this setting adds knowledge resources only. It does not add a Klai-specific MCP mutation tool, change Genie’s general FileMaker capabilities, or widen staging, Workbench, 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.

Klai tools update immediately after the setting is saved. Reconnect MCP clients so they refresh their guide index.

Section titled “Recommended agent workflow”

External agents should use the bridge in this order:

  1. Use fm_session action:status for a slim session summary; use its other actions only when the task needs them.
  2. Discover relevant guides, schemas, step records, and function records with fm_search and a non-empty query, or read genie://... resources directly. Search hits are never live target authority.
  3. Use fm_session when the task depends on the active/open FileMaker file. get_active reports the confirmed foreground ordinary document separately from Genie’s plug-in calculation context. Non-empty calculationContextFileName that names an open file is sufficient for live reads (metadata, script content, hooks) even when FileMaker is not frontmost; do not treat calculationContextMatchesForeground:false alone as a read stop when FileMaker is merely not the foreground app. activate is optional UI focus and a no-op only when the requested file owns that foreground document; Script Workspace never qualifies. Otherwise Genie shows and verifies an ordinary document using native file ownership when available. FileMaker 26 may expose an ownerless Cocoa title decorated as <WindowNames value> (<account>); Genie accepts that form only when comparison with every open file’s WindowNames(file) resolves one unique owner, so renamed-title collisions fail closed. Fail closed when calculation context is missing, conflicts with the requested file, or a confirmed foreground document diverges from calculation context (foreground_file_context_not_rebound). Activation does not stage, apply, or mutate data.
  4. Use fm_read target:script with an exact script identity, or genie://context/scripts, for current script evidence. Missing or ambiguous identity fails closed.
  5. For script authoring, discover the public schema and targeted step/function records with fm_search; then read the exact live target with fm_read.
  6. Use fm_read with one exact target (script, table, field, layout, relationship_summary, custom_function, or selection) when a staged request references real FileMaker objects.
  7. Use fm_evaluate with an expression for calculation proof. Use fm_stage kind:script|layout action:validate|compile_preview for non-mutating artifact checks; only action:stage queues Workbench.
  8. Use fm_query only for actual read-only row data, not field lists or relationship discovery.
  9. Stage exactly one item per fm_stage call with kind:script, kind:data, or kind:layout.
  10. Inspect Workbench with fm_workbench; use stage_changeset for an atomic 1–16 item ChangeSet and verify_apply for fail-closed verification. Apply and DATA Execute remain user actions in Genie UI.
  11. Call fm_run action:start only after an explicit user request to run one existing exact script. A queued start is not completion proof. When that script opts into Genie_ReturnScriptResult, use bounded read-only fm_run action:status polling for the returned request ID.

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 fm_search with a non-empty query when a client exposes tools but not resources. Exact key or uri filters can narrow a query to the same shipped content.

Current tool surface

Section titled “Current tool surface”
ToolUse forBoundary
fm_sessionSlim status, open files, active identity, bounded file metadata, activation, project context, or explicit metadata refresh.Context control only; no staging or FileMaker mutation.
fm_searchDiscovery over shipped guides, schemas, step/function catalogs, and layout-proof assets.Requires query; results are never live target authority.
fm_readExact live evidence for one script or metadata target.Exact identity is required; missing or ambiguous targets fail closed.
fm_queryRead-only SELECT preview and result rows.SELECT only; not field/schema discovery.
fm_evaluateFileMaker calculation evaluation.Calculation sandbox only; never validates artifacts or queues work.
fm_stageValidate, compile-preview, or queue one script or copy-only layout item; queue one DATA item.`action:validate
fm_workbenchlist, get, status, atomic stage_changeset, and fail-closed verify_apply.Apply and DATA Execute remain user UI actions.
fm_runaction:start runs one exact existing current-file script; action:status reads an optional retained callback result.Every start requires a new native confirmation. Status is read-only and never starts a script.
report_issueOptional limited diagnostics when Genie or a connected agent encounters a product problem.Never mutates FileMaker. Hidden and blocked when Product issue reports is off or Local MCP Privacy Mode is on.

Optional script results

Section titled “Optional script results”

Result capture is opt-in, not a default requirement. No Runner script is needed, and Genie does not replace or wrap the script parameter.

In the FileMaker script, wrap the result in the final Exit Script step:

Exit Script [ Text Result: Genie_ReturnScriptResult ( $result ) ]

Genie_ReturnScriptResult ( result ) reports the value to a pending result-aware Genie run and returns that same value unchanged. A parent FileMaker script can therefore continue to read the ordinary Get ( ScriptResult ). If a script has multiple Exit Script paths that should report results, use the function on each relevant path.

The MCP/AGENT flow is:

  1. Call fm_run with action:"start", the exact current file/script binding, and capture_result:true. Genie still asks the user to confirm this run.
  2. Keep the returned run_request_id.
  3. Poll fm_run with action:"status" and that exact ID. Status checks are read-only and do not display another confirmation.
  4. Treat only status:"completed" with script_completion_observed:true as callback completion evidence. A queued start alone is never enough.

Genie accepts only one retained result-aware run for the same exact file and script at a time. Unsolicited, wrong-script, duplicate, and overlapping callbacks are ignored or rejected. Results live only in plug-in memory, are limited to one megacharacter, time out after 15 minutes, and are retained for a bounded period. Scripts that do not use the callback continue to work with queued-only fm_run receipts and can be verified with the smallest relevant read-only tool.

What can be staged

Section titled “What can be staged”
LaneStage whenImportant limits
Script: newCreate one new FileMaker script.Use fm_stage kind:script with Script Schema and result_type: "new_script". One script per call.
Script: editEdit a named script using exact live or attached content.Use fm_read target:script or genie://context/scripts, then fm_stage kind:script; merge_ready is optional whole-script merge capability, not a staging gate.
DATAStage one supported FileMaker SQL data/schema request or migration plan.Use fm_stage kind:data; inspect exact metadata/relationships first.
Layout objectsCompile copy-only layout objects.Use fm_stage kind:layout; paste manually in FileMaker Layout mode.

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

Read-only Query stays with fm_query outside Workbench. Questions and planning stay in the IDE or AGENT.

Routing examples

Section titled “Routing examples”
User intentAgent should do
”Create a script that exports Customers as JSON.”Discover guides/schema, resolve exact metadata with fm_read, validate with fm_stage kind:script action:validate, then queue with fm_stage kind:script action:stage or return a Genie AGENT script artifact.
”Update the selected script to add logging before the API call.”Read exact content with fm_read target:script, then stage the targeted delta_edit with fm_stage kind:script.
”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 exact metadata, then stage one DATA request with fm_stage kind:data.
”Show me active customers.”Use fm_read for schema, then fm_query for read-only rows.
”Run GenieShowDialog and return its JSON result.”Resolve the exact current file/script, call fm_run action:start with capture_result:true, wait for the native confirmation, then poll the returned ID with read-only action:status. The target script must opt in with Genie_ReturnScriptResult.
”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 fm_read
  • 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”