[MCP-03] Add explicit, auditable, policy-gated state-changing tools

[jaavid]

Background

CoreLink is one product across multiple implementation repositories. This work is owned by mcp-server under EPIC-02.

Goal

Add explicit, auditable, policy-gated state-changing MCP tools only after the read-only/security boundary is accepted and a named Post-Beta use case justifies the capability.

Parent

• Primary Product Epic: EPIC-02
• Backlog ID: MCP-03

Scope

• Implement explicitly approved state-changing tools inside mcp-server.
• Require least-privilege authorization, explicit consent/confirmation, idempotency where applicable, audit events and safe retry/recovery behavior.
• Map every tool to version-identifiable public API/contracts; do not bypass public authorization/tenancy boundaries through internal runtime access.
• Validate supported behavior against the accepted mock/conformance path and retain Post-Beta evidence.

Out of Scope

• Read-only tooling already covered by MCP-02.
• Making state-changing MCP tools a prerequisite for the read-only MCP-04 RC package unless Product Council explicitly adds them to RC scope.
• Generic state-changing tools without a named customer/pilot use case and accepted security boundary.
• Treating successful implementation or packaging as Product Acceptance.

Acceptance Criteria

• Every state-changing tool has a named customer/pilot use case and explicit product-scope decision.
• MCP-01 security/tenant/consent/audit boundary is accepted for the operation class.
• MCP-02 read-only surface remains non-mutating and regression-safe.
• Authorization and cross-tenant/insufficient-scope paths fail closed.
• Explicit consent/confirmation semantics are demonstrated for sensitive operations.
• Idempotency, duplicate/retry, timeout and recovery behavior are deterministic where relevant.
• Audit evidence identifies actor, tenant, tool/action, target, outcome and correlation data without leaking secrets.
• Supported behavior passes against MOCK-03 or an equivalent accepted conformance environment.
• Documentation and maturity claims identify the exact supported contract/tool revision.

Dependencies and acceptance state

• Security prerequisite: MCP-01 accepted threat/auth/consent/audit boundary.
• Surface prerequisite: MCP-02 accepted read-only tool surface, so mutation semantics remain isolated from read-only guarantees.
• Evidence/product-gate prerequisite: named customer or pilot evidence plus explicit Product Council inclusion for the proposed state-changing operations.
• Conformance input: MOCK-03 or equivalent accepted sandbox before supported claims.
• Blocks: Post-Beta state-changing MCP documentation/acceptance and, only if explicitly included in a future release gate, the corresponding package compatibility evidence.
• Current dependency state: See the CoreLink Product organization Project.

Planning Metadata

• Type: Feature
• Priority snapshot: P2
• Product milestone snapshot: Post-Beta
• Domain snapshots: security, devex
• Area snapshot: backend
• Complexity: L
• Created in status: Triage
• Current status and DRI: See the CoreLink Product organization Project.
• Intended repository labels: type:feature

Definition of Done

• Acceptance criteria demonstrated.
• Named-use-case and scope-decision evidence is retained.
• Security/tenancy/consent/audit review is accepted.
• Required conformance and recovery checks pass.
• Public contract compatibility and provenance are reconciled.
• Documentation and release notes accurately state Post-Beta maturity.
• Pull request(s), exact dependency revisions and retained evidence are linked.