Skip to content

fleet-mcp: document required Fleet API endpoints and verify them at startup #50814

Description

@lukeheath

Goal

User story
As an operator running fleet-mcp with a least-privilege API-only user,
I want the MCP's required Fleet API endpoints documented and verified at startup
so that adding new MCP tools doesn't silently break deployments that use API endpoint restrictions.

Context

The dogfood Fleet Slack bot uses an API-only Observer+ user with API endpoint restrictions, configured by hand from a list posted in Slack in July. Since then the MCP toolset grew (e.g. get_software calls GET /api/v1/fleet/hosts/:id/software), so the allowlist drifted out of date and tools started failing with opaque 403s. Nothing catches this at deploy time.

The cmd/fleet-mcp README recommends a locked-down API-only user and links to the endpoint-restriction docs, but does not enumerate which endpoints the MCP actually needs.

Current required endpoints (from cmd/fleet-mcp on the v4.90.0 RC):

  • GET /api/v1/fleet/me
  • GET /api/v1/fleet/hosts
  • GET /api/v1/fleet/hosts/count
  • GET /api/v1/fleet/hosts/:id
  • GET /api/v1/fleet/hosts/:id/software
  • GET /api/v1/fleet/hosts/identifier/:identifier
  • GET /api/v1/fleet/host_summary
  • GET /api/v1/fleet/labels
  • GET /api/v1/fleet/labels/:id/hosts
  • GET /api/v1/fleet/fleets
  • GET /api/v1/fleet/fleets/:id/policies
  • GET /api/v1/fleet/fleets/:fleet_id/policies/:policy_id
  • GET /api/v1/fleet/global/policies
  • GET /api/v1/fleet/global/policies/:id
  • GET /api/v1/fleet/reports
  • POST /api/v1/fleet/reports/run
  • GET /api/v1/fleet/software/titles
  • GET /api/v1/fleet/software/titles/:id
  • POST /api/v1/fleet/hosts/:id/query

(GET /api/v1/fleet/results/websocket is also used but is a raw handler that is not subject to endpoint restrictions.)

Change

  • Document the required endpoint list in the cmd/fleet-mcp README and keep it updated when tools change.
  • Add a startup self-check that probes the required endpoints with the configured token and logs any that return 403, so a stale allowlist is caught at deploy time instead of by end users in Slack.

Metadata

Metadata

Assignees

Labels

#g-orchestrationOrchestration product groupquick-win~engineering-initiatedEngineering-initiated story, such as a bug, refactor, or contributor experience improvement.

Type

No type

Projects

Status
🐣 In progress

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions