@awesomate/fleet-mcp

Read-only fleet operations for the Awesomate team, from Claude Code. This is not a client tool — clients use @awesomate/hosting-mcp, which is a separate package, a separate token family, and a separate API surface.

Design, risk assessment and phasing: docs/design/fleet-operator-mcp.md.

Connect

1. Open https://hub.awesomate.ai/fleet/access. You need a fleet role — a superadmin grants it.
2. Name your device, create an activation code.
3. Run the command it gives you:

npx -y --package=@awesomate/fleet-mcp awesomate-fleet-bootstrap --code amt_fbs_...

4. Restart Claude Code and ask it to run fleet_whoami.

The code is valid for 10 minutes and is replay-safe — re-running after a failure is fine and mints a fresh token. The token itself is created on your machine and never passes through the clipboard.

Check the last line of the bootstrap output before believing it worked:

AWESOMATE FLEET CONNECT: SUCCESS
AWESOMATE FLEET CONNECT: PARTIAL issues=mcp-registration
AWESOMATE FLEET CONNECT: FAILED reason=no-role

What it can do

Seventeen read-only tools. Four are fleet-wide (fleet_whoami, fleet_overview, fleet_list_clients, fleet_switch); ten are per-client and require a session handle (health, executions, workflows, errors, alerts, hosting, subscription, knowledge, audit, tickets); three read the support desk without a session (fleet_desk_search, fleet_desk_ticket, fleet_desk_inbox), because "who else has hit this?" is a cross-client question. fleet_client_knowledge is counts-and-status only by policy (ADR-003) — it never returns a person's name, an alias or a document.

Support desk tools read the hub's own mirror of Teamwork Desk, including message bodies and internal staff notes, so a search over a thousand tickets is instant instead of a 15-minute walk of Desk's rate-limited API. Ticket data is correspondence addressed to Awesomate and is hub-owned — it does not go through a client's consent flags — but every read is audited in fleet_access_audit. The index backfills ~50 threads per 10 minutes after first deploy; results carry a coverage block and a note while it is incomplete. Design: docs/design/desk-mcp.md.

There is no default client. fleet_switch returns a handle naming exactly one slug for 30 minutes, and every client-scoped tool requires it. This is the central safety property, not an inconvenience: one credential reaches every tenant, so an ambient target is an incident waiting to happen. Every response is stamped with the slug it acted on.

Writes do not exist here. Not disabled — absent. Write scopes are not carried on the token at all; they will only ever be obtainable through a time-boxed, Chat-announced checkout against one client (Phase C).

Credentials

~/.awesomate/fleet-credentials.json, mode 0600, single identity, 14-day token.

No profiles, no .awesomate.json pin, no default account — unlike the client MCP, which needs all three because a client may own several accounts. Here the operator identity is fixed and the client is chosen per conversation.

Overrides for CI or debugging: AWESOMATE_FLEET_TOKEN, AWESOMATE_FLEET_API_BASE.

Never register the server with an env-baked token (claude mcp add --env AWESOMATE_FLEET_TOKEN=…). Env beats the credentials file, so the registration goes permanently stale after a re-pair and serves a dead identity that looks like a server bug. The bootstrap removes any it finds.

Revoking

Any device, any time, from https://hub.awesomate.ai/fleet/access. A superadmin can revoke anyone's devices, change roles, or offboard — role changes take effect within 30 seconds without touching tokens, and offboarding kills every device at once.

Development

npm install
npm run typecheck
npm run build      # esbuild bundle → dist/index.js

Point at a local hub with AWESOMATE_FLEET_API_BASE=http://localhost:4060.