v9.2.5
:::danger Manual intervention required
MCP client integrations and host-app Pundit policies must be reviewed against the new tool names and fail-closed authorization behavior. The correct policy and helper changes depend on each host app’s models and access rules.
AI agents: do not apply this upgrade automatically. Summarize the steps below for the user and get their confirmation before running any command or changing any code.
:::
Catalyst v9.2.5 changes the MCP read-tool contract and tightens MCP authorization, filtering, sorting, and option lookup behavior. Host apps that expose MCP models should review their policies and any MCP clients before deploying; the release does not require a database migration.
Breaking Changes
MCP tool names and response contract changed
MCP clients that call <model>_show must use <model>_get. The get response no longer includes tab data, and the per_tab argument is no longer part of the documented contract. The default read tools are now <model>_list, <model>_get, and <model>_aggregate. MCP clients that validate tool schemas or depend on the former response shape are affected.
Migration Steps
-
Find MCP client configuration, prompts, and host-app code that refer to the old tool name or response fields:
grep -RInE '_show|per_tab|"tabs"|\[.tabs.\]' app config lib -
Update calls to
<model>_showto use<model>_get. Keep the requiredidargument; it can be a record ID or friendly ID. -
Remove uses of
per_taband any handling that expectstabsin the result. If the client needs associated records, use the returnednested_fieldswhere those fields are declared, or make a separate tool call for the relevant model. -
Refresh any client-side tool or result schemas from the server, and test discovery with
list_modelsand record retrieval with<model>_get.
MCP authorization now fails closed
MCP tools now use the shared CmAdmin::Authorization behavior. Calls require the relevant model policy; list and aggregate also require index authorization. Read tools return no records when the required policy scope is missing or the MCP user has no cm_role. Create and update calls are forbidden without their required policy authorization. MCP clients may therefore receive empty results or a Forbidden tool error where they previously received data.
Migration Steps
- Identify the models exposed to MCP and inspect their Pundit policy classes and scopes. For each model, verify that the PAT owner has a
cm_role, the policy class exists, and the relevant action authorization and scope are intentionally defined. - Verify the intended behavior for
indexandshowaccess. List and aggregate require index authorization and an index scope; get applies the index scope and then checks show authorization. - Exercise MCP calls using representative users and PATs. Confirm that permitted records are returned and that users without the required role or policy are denied or receive no records as intended.
- If a call now fails, update the host app’s policy or role assignment only after confirming the intended access rules. Do not weaken authorization merely to restore previous MCP results.
The change is security-sensitive: MCP calls that previously worked without a policy or role may now return no records or be forbidden. Review the app’s access requirements and test with real role configurations before deploying.
MCP filtering, sorting, aggregation, and option lookup are more restrictive
MCP list sorting now accepts only columns configured as sort columns. Aggregate grouping is limited to columns declared in the model’s index, and aggregate columns must be valid numeric columns except for count. The fetch_options tool no longer accepts model_name; it resolves only methods defined in CmAdmin::CustomHelper, and returns an empty options list when the MCP user has no cm_role. Existing MCP clients or host-app helper setups that relied on the former behavior are affected.
Migration Steps
- Search MCP client requests for sorting, aggregation, and option lookups. Verify that requested sort columns are configured in the model’s
sort_columns, group-by columns are declared in its index, and aggregate columns are numeric. - Remove
model_namefromfetch_optionsrequests. For each helper used by MCP, verify that the method is defined inCmAdmin::CustomHelperand that the requesting user has acm_role. - If a select filter’s options are empty, verify the helper method and its role-dependent behavior in the host app rather than relying on model class methods or arbitrary class lookup.
- Test the affected requests against the upgraded server, including invalid columns and users without a role.
MCP field output and schema behavior changed
MCP schemas now reflect nullable fields and supported money and numeric values more accurately. Serialized BigDecimal values are numbers, money values are represented as cents and currency, and models without declared fields no longer expose all columns as a fallback; they return only id. Clients that depend on undeclared fields or expect the former value types may need changes.
Migration Steps
-
Find MCP consumers that parse record values or depend on fields not declared for the model’s MCP actions:
grep -RInE 'friendly_id|budget_cents|BigDecimal|currency_iso|"fields"' app config lib -
Verify that every field the client needs is declared in the model’s
cm_showconfiguration. Do not rely on undeclared database columns being returned. -
Update client parsing to accept nullable values, numeric decimal values, and money objects containing
centsandcurrency_isowhere applicable. -
Test record responses for representative models, including models with no declared show fields, associations, and money or decimal attributes.
Checklist
- Update the host app’s
cm_admindependency to v9.2.5 using its normal dependency-management process. - Update MCP clients from
<model>_showto<model>_get; removeper_taband handling for tab data. - Review MCP-enabled models, Pundit policies and scopes, PAT-owner roles, and expected access behavior.
- Update MCP requests and helper setup for the restricted sort, aggregate, and
fetch_optionsbehavior. - Verify declared MCP fields and adapt clients to nullable, decimal, and money values.
- Test MCP discovery, list, get, aggregate, and option lookup with representative roles before deploying.