feat(rbac): add tools.execute permission to team-scoped viewer role

[kimsehwan96]

🔗 Related Issue

Closes #3881

---

📝 Summary

Add tools.execute permission to the team-scoped viewer role so team members can invoke MCP tools without requiring the developer role (which also grants create/update/delete permissions). platform_viewer (global) is not modified.

---

🏷️ Type of Change

• Bug fix
• Feature / Enhancement
• Documentation
• Refactor
• Chore (deps, CI, tooling)
• Other (describe below)

---

🧪 Verification

Check	Command	Status
Lint suite	make lint	pass
Unit tests	make test	pass
Coverage ≥ 80%	make coverage	pass

I also checked e2e / playwright test in local environment.

---

✅ Checklist

• Code formatted (make black isort pre-commit)
• Tests added/updated for changes
• Documentation updated (if applicable)
• No secrets or credentials committed

---

📓 Notes (optional)

• Migration follows the same pattern established in fix(rbac): backfill admin.overview and servers.use permissions to viewer roles #3390 (abf8ac3b6008)
• E2E and Playwright tests verified on full docker-compose stack with fast_time_server

[crivetimihai]

Thanks @kimsehwan96 — this addresses #3878 cleanly. One concern: the viewer role is documented as read-only in CLAUDE.md and docs/docs/manage/rbac.md. Adding tools.execute changes the security model for all deployments. Consider:

1. Should this be a new role (e.g., executor) instead of modifying viewer?
2. If modifying viewer is the right call, the docs need updating.
3. DCO Signed-off-by line is required.

What are your thoughts?

[kimsehwan96]

@crivetimihai Thanks, good point.

Docs update: Both docs/docs/manage/rbac.md and CLAUDE.md are already updated in this PR — the viewer role table includestools.execute.
DCO Signed-off-by: Already present in the commit, and the DCO check is passing

I still think there's a reasonable argument for viewer having tools.execute — most MCP tools carry their own auth (OAuth, etc.), so the gateway-level restriction can feel like double-gating. But I understand the concern about breaking the read-only contract across all deployments.

What's your take — would you prefer keeping viewer strictly read-only, or is there room to reconsider?

If you'd rather keep it as-is, I can close this PR.

[marekdano]

Summary

This PR addresses issue #3881 by adding tools.execute permission to the team-scoped viewer role. This enables team members to execute MCP tools without requiring the developer role, which grants full CRUD permissions.

---

✅ Technical Implementation: Excellent

✅ Security Model: Correct Design

This is a least-privilege security enhancement, not a breaking change. Here's why:

Context from Issue #3881

PR #3390 added servers.use to viewer roles, allowing them to connect to Virtual Servers. However, without tools.execute, this permission was effectively useless for MCP workflows. The only alternative was granting the developer role, which includes full CRUD permissions—creating unnecessary operational risk.

This PR's Approach

• Team-scoped only: viewer (team members) gains tools.execute
• Global unchanged: platform_viewer (auto-assigned, no team membership) remains read-only
• Visibility filtering enforced: Team viewers can only execute:
  • Own team's tools ✅
  • Public tools ✅
  • NOT other teams' private tools (blocked by Layer 1 scoping) ❌

Operational Benefits

• Prevents forcing admins to grant developer role just for tool execution
• Reduces risk of accidental configuration changes
• Enables safe MCP tool usage for team members
• Addresses real multi-team deployment needs

---

✅ Test Coverage: Comprehensive

Updated tests verify:

• Team-scoped viewer can execute tools via /rpc tools/call ✅
• Cookie-based session tokens work correctly ✅
• Cross-team isolation maintained (Layer 1 scoping) ✅
• Permission matrix tests updated ✅
• E2E MCP RBAC transport tests updated ✅

---

📝 Minor Suggestion

Consider adding a note in CHANGELOG.md for release notes:

### Enhanced
- **RBAC:** Added `tools.execute` permission to team-scoped `viewer` role, enabling team members to execute MCP tools without requiring `developer` role (which grants full CRUD permissions). Addresses #3881. `platform_viewer` (global scope) remains read-only.

Otherwise LGTM 🚀