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 agentic handoff layer for tools like Codex, Cursor, or a local MCP-capable IDE agent. It lets the agent inspect Genie-owned context, make grounded routing decisions, and stage supported work back into Genie without bypassing review.

Local MCP is not a hidden apply channel. It is a localhost bridge with three jobs:

expose Genie-owned metadata and context to trusted local clients
give agents small read-only tools for schema and SELECT inspection
let agents stage separated CODE or DATA work into Workbench so you can review and run it inside Genie

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:

read metadata resources
read current context resources
call branded read-only Genie tools
ask Genie for its current capability and routing rules
stage supported CODE or DATA prompts into Workbench
stage agent-produced raw FileMaker XML into Workbench for user review when the current Genie MCP capability advertises XML staging

MCP tool calls do not generate code, mutate FileMaker, or apply changes. Running a staged item happens later from Genie Workbench and re-enters the normal Genie pipeline. Raw XML staging is also review-first: the MCP client can hand Genie an artifact, but the user still reviews it in Workbench and Genie before any FileMaker change.

The current package also includes compatibility fixes for Claude Desktop MCP clients.

Workbench panel showing a raw XML draft staged from Claude

Where to turn it on

Open Settings Guide and configure Local MCP Bridge.

You can control:

Enable Local MCP Bridge
Port
Status
Setup guide
Copy snippet

The setup guide can show:

Codex (Streamable HTTP)
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

Recommended agent workflow

External agents should use the bridge in this order:

Call genie_get_capabilities before staging work.
Inspect metadata and context with resources or read-only tools.
Use genie_query only for read-only SELECT preview/run tasks outside Workbench.
For script work that names layouts, tables, fields, scripts, or custom functions, call genie_prepare_metadata_selection.
Stage one supported CODE or DATA item with the purpose-built staging tool.
Tell the user to review the item in Genie Workbench.
The user runs, copies, or dismisses the item from Workbench.

When you run a Workbench item, Genie first applies the stored metadata selection, then sends the prompt through the same CODE or DATA pipeline you would use from the composer. CODE still uses scoped planning, bounded generation, validation, preview/copy/apply safety, and normal apply review. DATA still uses confirmation and SQL guardrails.

Resources Genie exposes

genie://metadata/all
genie://metadata/selected
genie://metadata/layouts
genie://metadata/tables
genie://metadata/scripts
genie://metadata/custom-functions
genie://context/live
genie://context/attached

Read-only tools

Tool	Use for	Required input
`genie_get_fields_on_layout`	Return trusted field names for one FileMaker layout.	`layoutName`
`genie_get_layout_info`	Return layout metadata plus fields visible on that layout.	`layoutName`
`genie_get_table_info`	Return table metadata and field details from loaded Genie metadata.	`tableName`
`genie_get_field_info`	Resolve one field with optional table/layout narrowing.	`fieldName`
`genie_get_fields_for_table`	Return schema fields for one table.	`tableName`
`genie_get_script_content`	Return saved XML for one Project Scripts entry. Read `scriptKey` from `genie://metadata/scripts`.	`scriptKey` preferred
`genie_query`	Preview or run a read-only SELECT using known metadata.	`intent`, `mode`

genie_query accepts mode: "preview" or mode: "run". It is separate from Workbench. Do not stage QUERY prompts into Workbench.

Workbench tools

Tool	Use for	Notes
`genie_get_capabilities`	Read the current routing contract and IDE-agent playbook.	Call this before staging.
`genie_prepare_metadata_selection`	Resolve loaded layouts, tables, fields, scripts, and custom functions into a `metadata_selection` bundle.	Use before metadata-grounded CODE.
`genie_stage_new_script`	Stage exactly one new FileMaker script request.	Preferred CODE creation tool.
`genie_stage_edit_script`	Stage exactly one edit for the script already attached or selected in Genie.	Requires Add Selection or Add Scripts context.
`genie_stage_data`	Stage one reviewed FileMaker SQL data/schema request.	DATA only.
`genie_list_workbench_items`	List staged Workbench items.	Review-only.
`genie_get_workbench_item`	Fetch one staged item by `job_id`.	Review-only.
`genie_get_job_status`	Fetch status for one staged item by `job_id`.	Review-only.

The specific tools matter. They teach the IDE agent to split work before it reaches Genie instead of relying on Genie to silently reroute mixed prompts.

What can be staged

Mode	Stage when	Important limits
CODE: new script	Create one new FileMaker script.	Use `genie_stage_new_script`. One Workbench item per script. No CREATE TABLE, ALTER TABLE, record DML, QUERY, ASK, or manual UI/relationship work.
CODE: edit script	Edit one script already attached or selected in Genie.	Use `genie_stage_edit_script`. No unattached named-script edits. No `create or replace` script operation.
DATA	Stage one supported FileMaker SQL data/schema request or migration-plan request.	Use `genie_stage_data`. Inspect metadata first. Do not use `IF NOT EXISTS`, SQL relationships/`REFERENCES`, script work, QUERY previews, or index-creation requests.
Raw XML artifact	Stage FileMaker XML produced by an agent for review.	Use only when the current `genie_get_capabilities` response advertises XML staging. It is not a resource-export path and does not apply during the MCP call.

Some FileMaker work is manual and should stay in the IDE instructions instead of Workbench:

table occurrences
relationships
layouts
Web Viewers
buttons
portals
layout objects
privilege or security object changes

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

When a prompt crosses those boundaries, Genie returns a normal ok: false tool result with recommended actions, tool calls, resources, templates, or metadata prechecks. Those results are meant for IDE agents to self-correct, not for users to debug JSON-RPC failures.

Routing examples

User intent	Agent should do
”Create a script that exports Customers as JSON.”	Optionally prepare metadata, then call `genie_stage_new_script`.
”Update the selected script to add logging before the API call.”	Confirm script context exists, optionally prepare metadata, then call `genie_stage_edit_script`.
”Create two scripts: Export Customers and Export Orders.”	Split into two `genie_stage_new_script` calls.
”Create table Customers with Email and Status fields.”	Inspect metadata, then call `genie_stage_data` for one clean DATA request.
”Show me active customers.”	Use `genie_query` with `mode: "preview"` or `mode: "run"`, not Workbench.
”Create a relationship graph and put a portal on the layout.”	Present manual FileMaker instructions locally. Do not stage.

IDE configuration

Use the setup guide in Settings to copy the right snippet for your client.

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

# Genie uses Streamable HTTP. Do not configure stdio for this bridge.
[mcp_servers.genie_local]
enabled = true
url = "http://127.0.0.1:3845/mcp"

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

For Cursor or generic MCP JSON clients, use:

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

What users should expect from failures

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

That means the right fix is usually to:

open the correct FileMaker file
refresh or recapture the right context
narrow the target so Genie knows what you mean
split unsupported bundled work into smaller supported Workbench stages
do manual FileMaker graph or layout work directly in FileMaker, then restage follow-up CODE or DATA work

Good uses

keeping an IDE-side agent aligned with FileMaker metadata
checking layout, table, and field details from the same machine
reading current Genie context while you work elsewhere
staging one reviewed script request from Cursor, Codex, or another MCP client
letting an IDE agent inspect metadata before asking Genie to create tables or generate one script