feat(intelligent-assistant): apply behavior-linked MCP tools permissions model

[michael-valdron]

Description

Aligns MCP permissions with the behavior-linked model used for chat and notebooks. Renames intelligent-assistant.mcp.read / intelligent-assistant.mcp.manage to mcp.tools.use / mcp.tools.manage, removes CRUD action attributes in favor of the generic use RBAC action, and updates backend wiring plus docs/policy examples.

Fixed

• https://redhat.atlassian.net/browse/RHIDP-15930
• https://redhat.atlassian.net/browse/RHIDP-15931

✔️ Checklist

• A changeset describing the change and affected packages. (more info)
• Added or Updated documentation
• Tests for new functionality and regression tests for bug fixes
• Screenshots attached (for UI changes)

Made with Cursor

[rhdh-gh-app]

Important

This PR includes changes that affect public-facing API. Please ensure you are adding/updating documentation for new features or behavior.

Changed Packages

Package Name	Package Path	Changeset Bump	Current Version
@red-hat-developer-hub/backstage-plugin-intelligent-assistant-backend	workspaces/intelligent-assistant/plugins/intelligent-assistant-backend	major	v3.2.0
@red-hat-developer-hub/backstage-plugin-intelligent-assistant-common	workspaces/intelligent-assistant/plugins/intelligent-assistant-common	major	v3.2.0
@red-hat-developer-hub/backstage-plugin-intelligent-assistant	workspaces/intelligent-assistant/plugins/intelligent-assistant	major	v3.2.0

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[rhdh-qodo-merge]

PR Summary by Qodo

Align MCP tools permissions with behavior-linked RBAC model

✨ Enhancement 📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Rename MCP permissions to mcp.tools.use/manage to match behavior-linked vocabulary.
• Remove CRUD-style permission action attributes; RBAC policies now use generic use.
• Update backend permission checks and all docs/policy examples for the new names.

Diagram

graph TD
  A[User / Role] --> B[RBAC policy CSV]
  B --> C[RBAC engine]
  C --> D[Backend router]
  D --> E[requirePermission]
  E --> F[IA permissions module]
  F --> G["mcp.tools.use/manage"]
  H[Docs / READMEs] --> B

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Backwards-compatible alias permissions (deprecate old names)

• ➕ Avoids immediate breakage for existing RBAC policies
• ➕ Enables a staged migration with deprecation warnings and a defined removal window
• ➖ Adds temporary complexity (two permission names to support)
• ➖ May prolong inconsistent usage across deployments

2. Provide an automated migration script/check

• ➕ Reduces operator error when updating rbac-policy.csv
• ➕ Can be used in CI to detect stale permission names
• ➖ Extra maintenance surface and versioning considerations
• ➖ Still requires users to run/opt into the migration tooling

Recommendation: The PR’s approach (single canonical rename to behavior-linked mcp.tools.* and removing CRUD-style attributes) is a clean alignment with the broader model. To reduce upgrade friction, consider a short-lived compatibility layer (old permission names mapped/accepted with deprecation messaging) or, at minimum, add a simple migration/validation step to detect old permissions in RBAC policy files during startup or CI.

Files changed (7) +38 / -24

Enhancement (2) +11 / -15

router.tsSwitch MCP routes to require 'iaMcpUsePermission' +3/-3

Switch MCP routes to require 'iaMcpUsePermission'

• Updates the MCP server listing and validation endpoints to require the renamed use permission. Aligns imports and route guards from 'iaMcpReadPermission' to 'iaMcpUsePermission'.

workspaces/intelligent-assistant/plugins/intelligent-assistant-backend/src/service/router.ts

permissions.tsRename MCP permissions to 'mcp.tools.*' and drop CRUD attributes +8/-12

Rename MCP permissions to 'mcp.tools.*' and drop CRUD attributes

• Replaces 'intelligent-assistant.mcp.read/manage' with 'mcp.tools.use/manage' and removes action attributes from both permissions. Renames 'iaMcpReadPermission' to 'iaMcpUsePermission' and updates the exported 'iaPermissions' list accordingly.

workspaces/intelligent-assistant/plugins/intelligent-assistant-common/src/permissions.ts

Documentation (3) +7 / -7

README.mdUpdate backend README for new MCP permissions and RBAC actions +4/-4

Update backend README for new MCP permissions and RBAC actions

• Replaces documented MCP permission names with 'mcp.tools.use' and 'mcp.tools.manage'. Updates example 'rbac-policy.csv' lines to use the generic 'use' action for MCP permissions.

workspaces/intelligent-assistant/plugins/intelligent-assistant-backend/README.md

report.api.mdExpose 'iaMcpUsePermission' in public API report +1/-1

Expose 'iaMcpUsePermission' in public API report

• Updates the public API surface report to reflect the renamed exported permission constant. Keeps 'iaMcpManagePermission' unchanged while replacing the read permission export with the new use permission.

workspaces/intelligent-assistant/plugins/intelligent-assistant-common/report.api.md

README.mdUpdate plugin README RBAC examples for MCP tools permissions +2/-2

Update plugin README RBAC examples for MCP tools permissions

• Adjusts documented RBAC policy examples to use 'mcp.tools.use/manage'. Updates MCP lines to use the generic 'use' action rather than CRUD-style actions.

workspaces/intelligent-assistant/plugins/intelligent-assistant/README.md

Other (2) +20 / -2

mcp-tools-permissions.mdAdd major-version changeset for MCP permission rename +18/-0

Add major-version changeset for MCP permission rename

• Introduces a breaking-change changeset documenting the MCP permission rename to 'mcp.tools.use/manage', removal of CRUD action attributes, and the 'iaMcpReadPermission' → 'iaMcpUsePermission' variable rename. Marks affected packages as major bumps and notes doc/policy updates.

workspaces/intelligent-assistant/.changeset/mcp-tools-permissions.md

rbac-policy.csvRename MCP permission entries in example RBAC policy +2/-2

Rename MCP permission entries in example RBAC policy

• Replaces 'intelligent-assistant.mcp.read/manage' entries with 'mcp.tools.use/manage'. Updates the action column to 'use' for both MCP permissions to match the new model.

workspaces/intelligent-assistant/rbac-policy.csv

[rhdh-qodo-merge]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can reply 'qodo' on any finding to push back, ask questions, or dig deeper

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 57.12%. Comparing base (a6c3450) to head (708dc62).
⚠️ Report is 16 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4249   +/-   ##
=======================================
  Coverage   57.12%   57.12%           
=======================================
  Files        2430     2430           
  Lines       96713    96713           
  Branches    26920    26911    -9     
=======================================
  Hits        55252    55252           
  Misses      41263    41263           
  Partials      198      198           

Flag	Coverage Δ		*Carryforward flag
adoption-insights	84.55% <ø> (ø)		Carriedforward from a6c3450
ai-integrations	69.16% <ø> (ø)		Carriedforward from a6c3450
app-defaults	69.79% <ø> (ø)		Carriedforward from a6c3450
augment	46.67% <ø> (ø)		Carriedforward from a6c3450
boost	76.77% <ø> (ø)		Carriedforward from a6c3450
bulk-import	72.79% <ø> (ø)		Carriedforward from a6c3450
cost-management	13.55% <ø> (ø)		Carriedforward from a6c3450
dcm	67.21% <ø> (ø)		Carriedforward from a6c3450
extensions	56.59% <ø> (ø)		Carriedforward from a6c3450
global-floating-action-button	71.18% <ø> (ø)		Carriedforward from a6c3450
global-header	66.50% <ø> (ø)		Carriedforward from a6c3450
homepage	47.50% <ø> (ø)		Carriedforward from a6c3450
install-dynamic-plugins	59.95% <ø> (ø)		Carriedforward from a6c3450
intelligent-assistant	75.24% <ø> (ø)
konflux	91.98% <ø> (ø)		Carriedforward from a6c3450
lightspeed	69.02% <ø> (ø)		Carriedforward from a6c3450
mcp-integrations	83.40% <ø> (ø)		Carriedforward from a6c3450
orchestrator	66.91% <ø> (ø)		Carriedforward from a6c3450
quickstart	63.74% <ø> (ø)		Carriedforward from a6c3450
sandbox	79.56% <ø> (ø)		Carriedforward from a6c3450
scorecard	86.17% <ø> (ø)		Carriedforward from a6c3450
theme	88.77% <ø> (ø)		Carriedforward from a6c3450
translations	5.12% <ø> (ø)		Carriedforward from a6c3450
x2a	55.02% <ø> (ø)		Carriedforward from a6c3450

*This pull request uses carry forward flags. Click here to find out more.

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a6c3450...708dc62. Read the comment docs.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.