Maintaining Platform MCP

Maintaining Platform MCP

The Platform MCP is a first-party product surface, not a separate integration to update later. When a change adds or alters a useful AI Control Plane outcome, assess the Platform MCP in the same change and keep its tools aligned where appropriate. This skill is the detailed source of truth; CLAUDE.md, REVIEW.md, and cubic.yaml contain concise activation and review rules that should stay aligned with it.

When a product change belongs in Platform MCP

Add or update a tool when the changed capability is a useful, repeatable outcome for an authenticated administrator or member to inspect or manage through an agent. Strong candidates include dashboard workflows, management operations, diagnostics, setup and repair actions, access controls, and product state users reasonably expect the AI Control Plane to understand.

Do not create a tool merely because a new API endpoint exists. Avoid exposing internal implementation operations, unbounded low-level primitives, secrets, workflows that cannot preserve the dashboard's safety controls, or capabilities whose authorization and product contract are not ready. Prefer one outcome-oriented tool over a mechanical copy of each HTTP endpoint.

For every relevant product change, make and document one of these decisions in the implementation or review:

• update an existing Platform MCP tool because its schema, behavior, terminology, permissions, or result is now stale;
• add a new Platform MCP tool because no existing tool represents the user outcome;
• make no Platform MCP change because the capability is internal, unsafe, redundant, or not useful through an agent.

Record the outcome, target resource, actor, existing-tool comparison, update/add/omit decision with rationale, and evidence that proves success. A silent omission is not a decision.

Source map

Search in this order before designing a new tool:

1. tool_*.go by product nouns and verbs, including synonyms such as pause/disable, share/distribute, and repair/setup;
2. registration and server-wide instructions in tools.go;
3. audience, scope, and authorization rules in descriptor.go;
4. the dashboard/API implementation and owning service tests, which define the current product safeguards;
5. shipped workflows under server/internal/plugins/platform_mcp_skills/.

Extend an existing outcome when that keeps the catalogue clearer. Lifecycle state changes can use tool_lifecycle_visibility.go as a concrete neighboring pattern.

Implementation workflow

1. Describe the changed user outcome, who may perform it, and the evidence that proves success.
2. Inspect related Platform MCP tools and distributed skills. Decide whether to update, add, or intentionally omit a tool.
3. Keep the tool contract outcome-oriented:
   • use clear names, titles, and descriptions in product language;
   • expose bounded typed inputs and outputs, not internal or vendor types;
   • return enough state for an agent to distinguish success, refusal, partial progress, and the next safe action;
   • never expose credentials, tokens, raw sensitive evidence, or hidden-resource signals.
4. Declare ToolMeta deliberately:
   • choose external and managed-assistant audiences independently;
   • use ProjectScopeExplicit when every caller must name a project, ProjectScopeDefaultable only when the product explicitly supports the organization's literal Default project, and ProjectScopeNone only when the operation is not scoped to one project;
   • for the external endpoint, preserve connection-time live organization-membership admission through Runtime.Handler/PrepareExternalContext separately from per-tool ToolMeta.Authorization; set live authorization and discovery scopes without relying on tool visibility as enforcement;
   • admit a tool to the managed assistant only when it works under assistant identity and exact-project scoping without an external OAuth connection.
5. For mutations, preserve the product workflow's safeguards. At minimum, check for a fresh target read, exact target selection, explicit confirmation, expected-version or equivalent concurrency protection, a stable idempotency key when replay is possible, atomic audit logging, and a post-mutation live read. Set MCP annotations accurately.
6. Register the tool through the shared Registrar path in tools.go. When a capability can be disabled or incompletely composed, follow the live/unavailable registration pairs in neighboring tool_*.go files: keep the same name, audiences, authorization, project scope, schema, and annotations, then return a bounded readable refusal rather than silently dropping the tool from the catalogue.
7. Update related surfaces when the workflow changes:
   • server instructions in tools.go for platform-wide behavior;
   • shipped Platform MCP skills when a multi-tool workflow or named tool changes;
   • setup resources, docs, and tool descriptions when terminology or next actions change.
8. Add focused tests for the live behavior and contract. As applicable, prove connection-time live membership admission in runtime_test.go, per-call authorization and discovery filtering, the listed input/output schema, each admitted audience, unavailable registration, secret/hidden-resource omissions, mutation safeguards, and the committed state returned after mutation. Put cross-tool invariants in descriptor_test.go; keep tool behavior beside the tool or service tests.