MCP tool reference

This page is for people who build with an external agent, such as Codex, Cursor or Claude Desktop, connected to Genie through Local MCP. To connect a client first, see Local MCP Bridge.

Tools

Genie exposes up to nine tools.

Tool	Plan	Use for
`fm_session`	Free	Status, open files, the active file, project context, and metadata refresh. Activating another file requires a paid plan.
`fm_search`	Free	Searching Genie’s guides, schemas, and script step and function catalogs. Requires `query`.
`fm_read`	Free	Reading one exact script or metadata target from the live file.
`fm_query`	Free	Read-only SELECT queries.
`fm_evaluate`	Paid	Evaluating a FileMaker calculation. It never changes the file.
`fm_stage`	Paid	Validating, previewing, staging or executing one change. See How staging works.
`fm_workbench`	Paid	Listing and checking Workbench items, removing a queued item, and staging a group of changes together. Removing an item never changes your file.
`fm_run`	Paid	`action:start` runs one existing script in the current file. `action:status` reads its optional result. Every start asks you to confirm.
`report_issue`	Free	Optional. Sends a short diagnostic report when Genie or the agent hits a product problem. Unavailable when Product issue reports is off in Settings or Local MCP Privacy Mode is on.

Reads are free. Staging and execution require a paid plan. After a plan change, reconnect the client so it refreshes its tools.

How staging works

Each fm_stage call handles one change of one kind. action:validate and action:compile_preview check or preview the change. They never change your file.

Without Auto apply: action:stage sends the change to Workbench. You review it there before anything changes in your file.
With Auto apply on: an explicit action:execute request runs the change directly. It is listed in Workbench › Submitted with its real outcome.

Auto apply is off by default and is turned on in Genie’s Settings. Access, file and Privacy checks apply either way. fm_run asks you to confirm every script run, even with Auto apply on. See Review, Auto apply and Undo.

When Claude Code or Codex calls the tools

Claude Code and Codex running inside Genie (Claude Code and Codex) use these same nine tools through Genie’s local tool server. Their calls behave like any other MCP client’s, with the same Auto apply rules:

With Auto apply off, action:stage queues the change for your review. In Genie it appears as a card with Apply, Review and Copy in the program’s conversation, and in Workbench if the card cannot be delivered.
With Auto apply on, action:stage and an explicit action:execute apply the change directly, with Genie’s native checks and read-back. This includes script folders, renames and HookSet installs (kind:script_folders) and layout writes where your FileMaker build allows them.
The paid plan, the file and Privacy checks, and Local MCP Privacy Mode still apply. fm_run still asks you to confirm every start.
Unlike Genie’s own Agent, nothing checks an engine’s change against what you asked.

Reads stay Free, and staging and execution need a paid plan.

What fm_stage accepts

Kind	Use for
`script`	One new script (`result_type: "new_script"`) or one edit to a named script (`result_type: "delta_edit"`).
`script_folders`	Creating script folders and moving scripts into them. Runs only with Auto apply on.
`layout`	Creating a layout, adding objects to one, or editing objects on one, described in Layout Schema. With Auto apply on, an explicit `action:execute` writes it to your file on macOS. With Auto apply off, it waits in Workbench, where you apply it after a confirmation or copy the objects to paste yourself. On Windows, layout objects are copied.
`data`	One FileMaker SQL data or schema change.
`table_occurrence`	Adding a table occurrence to the relationship graph.
`relationship_graph`	Creating or editing relationships, and arranging the graph.

Read-only queries stay with fm_query, outside Workbench. Questions and planning stay in the agent or in Genie’s chat.

Staging scripts

Stage one new script or one edit to one named script per call. For several scripts, make one fm_stage call per script.
Before an edit, read the script with fm_read target:script. It returns the script as numbered lines. Anchor each edit to those one-based line numbers.
Find the Script Schema and the exact step and function records with fm_search before you write steps.
When metadata names matter, read them with fm_read target:selection and pass the returned metadata_selection with the staged item.
Stage scripts and data changes as separate items.
Validate with action:validate before you stage.

Staging data and schema

Read the exact tables, fields and relationships with fm_read first, then stage one request with fm_stage kind:data. Before a data change runs, FileMaker shows a confirmation with the exact SQL and values.

Optional script results

Result capture is opt-in. 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 Genie run and returns that same value unchanged. A parent FileMaker script can still read Get ( ScriptResult ). If a script has several Exit Script paths that should report results, use the function on each one.

The flow:

Call fm_run with action:"start", the exact current file and script, and capture_result:true. Genie asks you to confirm the run.
Keep the returned run_request_id.
Poll fm_run with action:"status" and that ID. Status checks are read-only and do not ask for another confirmation.
Treat the run as finished only when status is "completed" and script_completion_observed is true. A queued start alone is not enough.

Genie keeps one result-aware run at a time for the same file and script. Unrequested, wrong-script, duplicate, and overlapping callbacks are ignored. Results stay in plug-in memory only, are limited to one million characters, and time out after 15 minutes. Scripts that don’t use the function still run; check their effect with the smallest relevant read-only tool.

Routing examples

User intent	Agent should do
”Create a script that exports Customers as JSON.”	Find the guides and schema, read the exact metadata with `fm_read`, validate with `fm_stage kind:script action:validate`, then stage with `fm_stage kind:script action:stage`.
”Update the selected script to add logging before the API call.”	Read the exact content with `fm_read target:script`, then stage a targeted `delta_edit` with `fm_stage kind:script`.
”Create two scripts: Export Customers and Export Orders.”	Make two separate stage calls.
”Create table Customers with Email and Status fields.”	Inspect the exact metadata, then stage one data request with `fm_stage kind:data`.
”Show me active customers.”	Use `fm_read` for the schema, then `fm_query` for read-only rows.
”Run GenieShowDialog and return its JSON result.”	Resolve the exact file and script, call `fm_run action:start` with `capture_result:true`, wait for your confirmation, then poll the returned ID with `action:status`. The script must use `Genie_ReturnScriptResult`.

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 project name, description, enabled rules, naming conventions, reusable patterns, script template, and guidance_sources, which shows whether each value came from the Project or from Generic Personalization. This guidance shapes names, comments, patterns, and script structure. It never changes what the agent is allowed to do.

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 Klai integration is on:

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 narrow a query to the same content.