Story 5: MCP Platform Tools

This epic is the single source of truth for the MCP platform tool surface: what ships today and what is still to build. New tools are filed here.

## Where we are

| Surface | Implemented | Planned (specced, not built) | Excluded by design |
| --- | --- | --- | --- |
| Platform tools | 75 | ~51 | credential-issuing + admin ([5.A / #7684](https://github.com/FlowFuse/flowfuse/issues/7684)) |
| Flow-building tools (in-editor) | 28 | none | none |
| UI / navigation | 3 | none | none |
| **Total** | **106** | **~51** | n/a |

Every read scope has shipped (all `-a` sub-issues closed). The open work is writes (`-b`) and deletes (`-c`). In short: agents can drive the whole **build** today (create apps, instances, devices, snapshots, and whole flows in the editor) up to (but not including) **deploy** and lifecycle/config mutation.

## Status by area

Legend: **R** read · **W** write · **D** delete. **Completed** = closed sub-issues, **To do** = open.

| Area | Live today | Still to build | Completed | To do |
| --- | --- | --- | --- | --- |
| Instances (hosted + remote) | all reads + 3 W | 11 W · 4 D | [5.11-a](https://github.com/FlowFuse/flowfuse/issues/7705) | [5.1](https://github.com/FlowFuse/flowfuse/issues/7670) · [5.1-b](https://github.com/FlowFuse/flowfuse/issues/7685) · [5.1-c](https://github.com/FlowFuse/flowfuse/issues/7686) · [5.11](https://github.com/FlowFuse/flowfuse/issues/7680) · [5.11-b](https://github.com/FlowFuse/flowfuse/issues/7706) · [5.11-c](https://github.com/FlowFuse/flowfuse/issues/7707) |
| Snapshots | all reads + 1 W | 4 W · 1 D | [5.2-a](https://github.com/FlowFuse/flowfuse/issues/7687) | [5.2](https://github.com/FlowFuse/flowfuse/issues/7671) · [5.2-b](https://github.com/FlowFuse/flowfuse/issues/7688) · [5.2-c](https://github.com/FlowFuse/flowfuse/issues/7689) |
| Applications | all reads + 1 W | 1 W · 1 D | [5.3-a](https://github.com/FlowFuse/flowfuse/issues/7690) | [5.3](https://github.com/FlowFuse/flowfuse/issues/7672) · [5.3-b](https://github.com/FlowFuse/flowfuse/issues/7691) · [5.3-c](https://github.com/FlowFuse/flowfuse/issues/7692) |
| Pipelines (DevOps) | all reads | 5 W · 2 D | [5.5-a](https://github.com/FlowFuse/flowfuse/issues/7696) | [5.5](https://github.com/FlowFuse/flowfuse/issues/7674) · [5.5-b](https://github.com/FlowFuse/flowfuse/issues/7697) · [5.5-c](https://github.com/FlowFuse/flowfuse/issues/7698) |
| Device groups (fleet) | all reads | 4 W · 1 D | [5.6-a](https://github.com/FlowFuse/flowfuse/issues/7699) | [5.6](https://github.com/FlowFuse/flowfuse/issues/7675) · [5.6-b](https://github.com/FlowFuse/flowfuse/issues/7700) · [5.6-c](https://github.com/FlowFuse/flowfuse/issues/7701) |
| Teams & membership | all reads | 5 W · 2 D · 1 R blocked | [5.4-a](https://github.com/FlowFuse/flowfuse/issues/7693) | [5.4](https://github.com/FlowFuse/flowfuse/issues/7673) · [5.4-b](https://github.com/FlowFuse/flowfuse/issues/7694) · [5.4-c](https://github.com/FlowFuse/flowfuse/issues/7695) · [5.4-a.3](https://github.com/FlowFuse/flowfuse/issues/8242) |
| FlowFuse Tables | all reads | none specced | [5.4-a.2](https://github.com/FlowFuse/flowfuse/issues/7989) | none |
| Broker & MQTT | all reads | 3 W · 2 D | [5.13-a](https://github.com/FlowFuse/flowfuse/issues/7711) | [5.13](https://github.com/FlowFuse/flowfuse/issues/7682) · [5.13-b](https://github.com/FlowFuse/flowfuse/issues/7712) · [5.13-c](https://github.com/FlowFuse/flowfuse/issues/7713) |
| Notifications & self-service | all reads | 3 W · 1 D | [5.9-a](https://github.com/FlowFuse/flowfuse/issues/7702) | [5.9](https://github.com/FlowFuse/flowfuse/issues/7678) · [5.9-b](https://github.com/FlowFuse/flowfuse/issues/7703) · [5.9-c](https://github.com/FlowFuse/flowfuse/issues/7704) |
| Bill of materials | done (R only) | none | [5.7](https://github.com/FlowFuse/flowfuse/issues/7676) | none |
| Search | done (R only) | none | [5.8](https://github.com/FlowFuse/flowfuse/issues/7677) | none |
| Platform catalog | done (R + 1 W) | none (writes are admin-only) | [5.10](https://github.com/FlowFuse/flowfuse/issues/7679) | none |
| Billing | dropped | none | [5.14](https://github.com/FlowFuse/flowfuse/issues/7683) (not required) | none |

## What's still to build (the open work)

Sibling actions are consolidated into one tool with an `action`/`instanceType` enum where they share a concept.

**Instances** [5.1-b](https://github.com/FlowFuse/flowfuse/issues/7685) / [5.11-b](https://github.com/FlowFuse/flowfuse/issues/7706) (W): `platform_instance_action` (start/stop/restart/suspend), `platform_update_hosted_instance_env`, `platform_update_hosted_instance_settings`, `platform_import_hosted_instance_flows`, `platform_set_instance_config`, `platform_update_instance_file`, `platform_upload_instance_file`, `platform_create_instance_http_token`, `platform_update_instance_http_token`, `platform_update_remote_instance_settings`, `platform_set_remote_instance_mode`. [5.1-c](https://github.com/FlowFuse/flowfuse/issues/7686) / [5.11-c](https://github.com/FlowFuse/flowfuse/issues/7707) (D): `platform_delete_instance`, `platform_rollback_hosted_instance`, `platform_delete_instance_file`, `platform_delete_instance_http_token`.

**Snapshots** [5.2-b](https://github.com/FlowFuse/flowfuse/issues/7688) (W): `platform_export_snapshot`, `platform_import_snapshot`, `platform_update_snapshot`, `platform_set_instance_device_target`. [5.2-c](https://github.com/FlowFuse/flowfuse/issues/7689) (D): `platform_delete_snapshot`.

**Applications** [5.3-b](https://github.com/FlowFuse/flowfuse/issues/7691) (W): `platform_update_application`. [5.3-c](https://github.com/FlowFuse/flowfuse/issues/7692) (D): `platform_delete_application`.

**Pipelines** [5.5-b](https://github.com/FlowFuse/flowfuse/issues/7697) (W): `platform_deploy_pipeline_stage`, `platform_create_pipeline`, `platform_update_pipeline`, `platform_add_pipeline_stage`, `platform_update_pipeline_stage`. [5.5-c](https://github.com/FlowFuse/flowfuse/issues/7698) (D): `platform_delete_pipeline`, `platform_delete_pipeline_stage`.

**Device groups** [5.6-b](https://github.com/FlowFuse/flowfuse/issues/7700) (W): `platform_create_device_group`, `platform_update_device_group`, `platform_update_device_group_membership`, `platform_update_device_group_settings`. [5.6-c](https://github.com/FlowFuse/flowfuse/issues/7701) (D): `platform_delete_device_group`.

**Teams & membership** [5.4-b](https://github.com/FlowFuse/flowfuse/issues/7694) (W): `platform_create_team`, `platform_update_team`, `platform_change_member_role`, `platform_invite_team_member`, `platform_resend_team_invitation`. [5.4-c](https://github.com/FlowFuse/flowfuse/issues/7695) (D): `platform_remove_team_member`, `platform_revoke_team_invitation`. Blocked (R): `platform_list_library_entries` on [#8242](https://github.com/FlowFuse/flowfuse/issues/8242).

**Broker & MQTT** [5.13-b](https://github.com/FlowFuse/flowfuse/issues/7712) (W): `platform_broker_lifecycle_action`, `platform_create_broker_topic`, `platform_update_broker_topic`. [5.13-c](https://github.com/FlowFuse/flowfuse/issues/7713) (D): `platform_delete_broker_topic`, `platform_delete_broker_client`. Broker credential mint / password / 3rd-party register / raw fetch stay excluded ([#7513](https://github.com/FlowFuse/flowfuse/issues/7513)).

**Notifications & self-service** [5.9-b](https://github.com/FlowFuse/flowfuse/issues/7703) (W): `platform_set_notification_read_state`, `platform_respond_to_team_invitation`, `platform_update_profile`. [5.9-c](https://github.com/FlowFuse/flowfuse/issues/7704) (D): `platform_delete_notification`. Password / MFA / account deletion / token management stay excluded.

## What's already delivered

Live in production today. Reads are complete across every scope (the `-a` sub-issues); the writes below shipped as the baseline create tools.

**Instances** [5.11-a](https://github.com/FlowFuse/flowfuse/issues/7705) (R): `platform_list_hosted_instances`, `platform_get_hosted_instance`, `platform_get_hosted_instance_status`, `platform_get_hosted_instance_logs`, `platform_get_hosted_instance_resources`, `platform_get_hosted_instance_config`, `platform_get_hosted_instance_custom_hostname`, `platform_list_hosted_instance_files`, `platform_check_hosted_instance_name_availability`, `platform_list_team_dashboard_instances`, `platform_list_remote_instances`, `platform_get_remote_instance`, `platform_get_remote_instance_status`, `platform_list_instance_http_tokens`, `platform_get_instance_history`, `platform_get_instance_audit_log`, `platform_get_hosted_instance_editor_url`, `platform_get_hosted_instance_overview_url`. (W): `platform_create_hosted_instance`, `platform_create_remote_instance`, `platform_assign_remote_instance_to_application`.

**Snapshots** [5.2-a](https://github.com/FlowFuse/flowfuse/issues/7687) (R): `platform_list_instance_snapshots`, `platform_get_snapshot`, `platform_get_snapshot_full`, `platform_get_hosted_instance_device_target_snapshot`. (W): `platform_create_instance_snapshot`.

**Applications** [5.3-a](https://github.com/FlowFuse/flowfuse/issues/7690) (R): `platform_list_applications`, `platform_get_application`, `platform_get_application_audit_log`, `platform_list_application_snapshots`, `platform_list_team_instance_statuses`. (W): `platform_create_application`.

**Pipelines** [5.5-a](https://github.com/FlowFuse/flowfuse/issues/7696) (R): `platform_list_pipelines`, `platform_get_pipeline_stage`.

**Device groups** [5.6-a](https://github.com/FlowFuse/flowfuse/issues/7699) (R): `platform_list_team_device_groups`, `platform_list_application_device_groups`, `platform_get_application_device_group`.

**Teams & membership** [5.4-a](https://github.com/FlowFuse/flowfuse/issues/7693) (R): `platform_list_teams`, `platform_get_team`, `platform_get_team_membership`, `platform_get_team_instance_counts`, `platform_list_team_members`, `platform_list_team_invitations`, `platform_get_team_audit_log`, `platform_list_team_npm_packages`, `platform_list_team_git_tokens`.

**FlowFuse Tables** [5.4-a.2](https://github.com/FlowFuse/flowfuse/issues/7989) (R): `platform_list_team_databases`, `platform_get_team_database`, `platform_list_database_tables`, `platform_get_database_table`, `platform_query_database_table_data`.

**Broker & MQTT** [5.13-a](https://github.com/FlowFuse/flowfuse/issues/7711) (R): `platform_list_broker_clients`, `platform_get_broker_client`, `platform_list_brokers`, `platform_get_broker`, `platform_list_broker_topics`, `platform_get_broker_schema`.

**Notifications & self-service** [5.9-a](https://github.com/FlowFuse/flowfuse/issues/7702) (R): `platform_get_active_user`, `platform_list_notifications`, `platform_list_own_invitations`.

**Bill of materials** [5.7](https://github.com/FlowFuse/flowfuse/issues/7676) (R): `platform_get_team_bill_of_materials`, `platform_get_application_bill_of_materials`.

**Search** [5.8](https://github.com/FlowFuse/flowfuse/issues/7677) (R): `platform_search_team_resources`, `platform_search_instances`.

**Platform catalog** [5.10](https://github.com/FlowFuse/flowfuse/issues/7679) (R): `platform_list_hosted_instance_types`, `platform_list_templates`, `platform_get_template`, `platform_list_blueprints`, `platform_get_blueprint`, `platform_list_team_types`, `platform_get_team_type`, `platform_list_browser_sessions`, `platform_get_active_browser_session`. (W): `platform_set_active_browser_session`.

Beyond platform tools, all **28 flow-building** (in-editor) and **3 UI/navigation** tools are fully delivered.

## Excluded by design ([5.A / #7684](https://github.com/FlowFuse/flowfuse/issues/7684))

Mapped so the decision stays reversible, deliberately not exposed as tools:

- **Platform admin**: stats, license, announcements, settings, arbitrary-user CRUD, SSO providers (admin-role only).
- **Catalog writes**: create/edit/delete stacks, templates, project-types, team-types, blueprints (admin only).
- **Credential-issuing**: provisioning-token mint, broker credentials/passwords, npm/git token issuance, device credential regen, device tunnel/editor tokens, password/MFA/PAT self-management (escalation risk).
- **Runtime plumbing**: device-agent live routes, Node-RED storage routes, internal registration endpoints (not user-facing).
- **Streaming**: device log/resource streaming (MQTT streaming shape, not request/response).