fleetalert-mcp
This server exposes read-only FleetAlert observability tools for alerts, investigation traces, usage, and activity.
List all demo alerts with machine, severity, and status.
Get one alert’s status, proposed fix, confidence, root-cause summary, and related email/detection data.
Summarize investigation history by round, including outcomes, steps, model calls, tokens, and cost.
Retrieve raw trace spans with full inputs/outputs, optionally filtered by kind and limited by count.
Check today’s investigation count and model spend against daily caps.
View recent cross-alert activity and guardrail/human decision events.
No write/action tools are exposed in this schema; it cannot start investigations or confirm/reject fixes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@fleetalert-mcp List the FleetAlert alerts and summarize the trace for the one awaiting confirmation"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
fleetalert-mcp
An MCP server for FleetAlert AI, the agentic alert-investigation demo in mbgolden/fleetalert-ai. It lets Claude Code, Claude Desktop, claude.ai or any MCP client read FleetAlert's alerts and investigation traces, start investigations, and confirm or reject a proposed fix, with the same safety tiers FleetAlert enforces internally, plus the auth (bearer tokens and an OAuth 2.1 authorization server) and rate limits the public demo API does not have itself.
Built on the MCP Python SDK v2 (protocol 2026-07-28), Python 3.12.
What it demonstrates
Typed tools, structured output | Every tool has a JSON Schema input (from type hints) and a JSON Schema output (from pydantic models). |
Safety tiers carried through the protocol | Tools are tagged |
Human approval, structurally |
|
The server is the auth boundary | Over Streamable HTTP, requests need a bearer token ( |
Rate limits that protect the upstream budget | FleetAlert caps itself at 50 investigations or $1.25 a day. This server adds per-principal buckets (all tools, and a tighter one for tools that spend budget) and a global bucket in front of the upstream API. A refusal is a tool result the model can read ("retry in 12 s"), not a protocol error it never sees. |
Audit and metrics | One JSON line per tool call: principal, tier, tool, outcome, duration. |
Tested without the network | The SDK's in-memory client drives the real server against a mocked FleetAlert API, including the elicitation round-trip for |
Related MCP server: enterprise-mcp
Tools
Tool | Tier | What it does |
| read_only | Every demo alert with machine, severity and status |
| read_only | One alert's status, proposed fix, confidence and root-cause summary |
| read_only | Investigation history, one summary per round |
| read_only | Raw spans with full input and output, filterable by kind |
| read_only | Today's spend against the daily cost guard |
| read_only | Recent cross-alert activity feed |
| proposes_action | Start an agent round on an open alert (spends budget) |
| proposes_action | Deliver the demo's seeded maintenance email |
| proposes_action | Run the rule-based detector once |
| executes_action | Ask the human, then confirm the proposed fix upstream |
| executes_action | Reject the proposed fix with a reason |
Also: resources fleetalert://alerts and fleetalert://alerts/{alert_id}/trace,
and a triage_alert prompt that walks a model through reviewing one alert's
evidence and recommending confirm, reject or wait.
Quick start
Claude Desktop or claude.ai: Settings → Connectors → Add custom connector,
URL https://xx8eypbgv2.execute-api.us-east-1.amazonaws.com/mcp, no client
id or secret. Claude opens the server's consent page; press Connect to
sign in as the read-only visitor. An operator who has a governor key can
paste it there instead and the connector gets that key's tier.
Claude Code, against the same hosted instance with the published read-only visitor token (nothing to install):
claude mcp add --transport http fleetalert https://xx8eypbgv2.execute-api.us-east-1.amazonaws.com/mcp \
--header "Authorization: Bearer d2067598688a6ca159dec88d3b0911805d09a2940513e869"Or run it locally over stdio, straight from GitHub:
claude mcp add fleetalert -- uvx --from git+https://github.com/mbgolden/fleetalert-mcp fleetalert-mcpTo allow actions, set the tier (the tools appear only when you do):
claude mcp add fleetalert -e FLEETALERT_MCP_TIER=executes_action -- uvx --from git+https://github.com/mbgolden/fleetalert-mcp fleetalert-mcpClaude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"fleetalert": {
"command": "uvx",
"args": ["--from", "git+https://github.com/mbgolden/fleetalert-mcp", "fleetalert-mcp"],
"env": { "FLEETALERT_MCP_TIER": "read_only" }
}
}
}Then ask: "List the FleetAlert alerts and summarise the trace for the one awaiting confirmation."
Configuration
All settings are FLEETALERT_MCP_* environment variables (a .env file in
the working directory is honoured; see .env.example).
Variable | Default | Meaning |
|
| Highest tier of tool to register: |
| the live demo | FleetAlert API base URL |
| empty | HTTP mode bearer tokens: |
|
| Public URL of this server in HTTP mode (for the protected-resource metadata) |
|
| Run HTTP mode without tokens, loopback only |
| unset | Fixed key (32+ characters) sealing elicitation state, and every OAuth record, across processes (required on Lambda) |
|
| Also serve an OAuth 2.1 authorization server ( |
|
| Per principal, every tool |
|
| Per principal, tools above read_only |
|
| Across all principals |
|
|
HTTP mode
export FLEETALERT_MCP_TIER=executes_action
export FLEETALERT_MCP_TOKENS="ops:executes_action:$(openssl rand -hex 24),ci:read_only:$(openssl rand -hex 24)"
fleetalert-mcp --transport http --host 0.0.0.0 --port 8000POST /mcpis the MCP endpoint. Without a validAuthorization: Bearerheader it answers401with aWWW-Authenticateheader pointing at/.well-known/oauth-protected-resource/mcp.The
citoken above sees every tool the server registers but is refused on anything aboveread_only, with a message the model can read.GET /healthzandGET /metricsare unauthenticated and JSON.With
FLEETALERT_MCP_OAUTH_ENABLED=1the same process is the authorization server the metadata points at. A client registers itself, sends the person to/consent, and exchanges the code for a token whose scope is a tier. Static tokens keep working alongside.
The server refuses to start in HTTP mode without tokens unless
FLEETALERT_MCP_ALLOW_ANONYMOUS_HTTP=1 and the host is loopback.
Hosted on AWS Lambda
The same server runs as a Lambda behind API Gateway, which is how the
FleetAlert demo exposes it. Install the extra and point the function at
fleetalert_mcp.lambda_handler.handler:
uv pip install "fleetalert-mcp[lambda] @ git+https://github.com/mbgolden/fleetalert-mcp@v0.3.1"Variable | |
| the API Gateway endpoint (issuer and resource for the bearer auth) |
| a Secrets Manager secret holding |
| the server's tier; tokens narrow it per client |
|
|
The Lambda serves protocol 2026-07-28 in stateless JSON mode (one POST per
request, no sessions, no SSE). state_key (32+ characters, for example
secrets.token_hex(32)) seals the elicitation state that confirm_fix
carries between two requests, and every OAuth client, code and token, so
they work across instances with no table behind them. The Terraform
that deploys it lives in
fleetalert-ai (its ADR-0025);
see ADR-0005
here for the reasoning.
The FleetAlert demo's instance is live. Connect with its published read-only visitor token:
claude mcp add --transport http fleetalert https://xx8eypbgv2.execute-api.us-east-1.amazonaws.com/mcp \
--header "Authorization: Bearer d2067598688a6ca159dec88d3b0911805d09a2940513e869"Health: https://xx8eypbgv2.execute-api.us-east-1.amazonaws.com/healthz.
How the OAuth sign-in works
client: GET /.well-known/oauth-protected-resource/mcp -> authorization server = this server
client: POST /register {redirect_uris, ...} -> client_id = sealed(registration)
client: GET /authorize?client_id&code_challenge&redirect_uri&state
server: 302 /consent?txn=sealed(request)
human: Connect (visitor) or paste an operator key
server: 302 redirect_uri?code=sealed(grant, client_id, challenge)&state
client: POST /token {code, code_verifier} -> access = sealed(grant, 1 h), refresh = sealed(grant, 30 d)
client: POST /mcp Authorization: Bearer fmca_... -> principal visitor, tier read_onlyNothing is stored: each record is AES-GCM sealed under a key derived from
state_key for that one purpose, with its expiry inside. The grant's scope is
a tier name, so an OAuth token narrows the server exactly as a static one
does, and the audit log names the principal (visitor, ops), not the app.
See ADR-0007.
How confirm_fix works
model: confirm_fix(alert_id="ALERT-1007")
server: GET /status -> awaiting_confirmation? (else: tool error, nothing sent)
server: elicit -> client shows the human the proposed fix, confidence, root cause
human: approve=true human: approve=false / decline / cancel
server: GET /status -> token server: result "not_confirmed", nothing sent
server: POST /confirm {token}
model: result "confirmed" (the token is not in it)If the client did not advertise elicitation, the tool is refused before any upstream call, with a message pointing the human at the FleetAlert web UI.
Development
uv sync --group dev
uv run ruff check . && uv run ruff format --check .
uv run mypy src
uv run bandit -q -r src
uv run pytest
FLEETALERT_MCP_LIVE=1 uv run pytest tests/test_live.py # read-only, against the real demoRun locally over stdio with uv run fleetalert-mcp, or over HTTP as above.
uv run mcp dev src/fleetalert_mcp/cli.py is not supported (the server is
built by build_server() from settings); use the MCP Inspector against the
HTTP endpoint instead.
Repo layout
src/fleetalert_mcp/
server.py tools, resources, prompt; build_server(settings)
tiers.py the three tiers and their ordering
guard.py middleware: principal, tier check, rate limits, audit log, metrics
auth.py static bearer tokens as a TokenVerifier
oauth.py stateless OAuth 2.1 authorization server (sealed records) and the consent page
ratelimit.py token buckets
upstream.py typed httpx client for the FleetAlert API
summarize.py spans -> per-round summary
config.py FLEETALERT_MCP_* settings
cli.py stdio / HTTP entry point
http.py bearer auth settings and /healthz, /metrics, shared by uvicorn and Lambda
lambda_handler.py AWS Lambda entry point (Mangum, stateless JSON mode)
tests/ in-memory client against a mocked API; one live smoke test
docs/decisions/ ADR log
docs/BACKLOG.md follow-ups, with the evidence that raised themDecisions
ADR-0001: a standalone repo on the Python SDK v2, not a folder in fleetalert-ai
ADR-0002: tiers decide which tools exist, default read-only, tokens narrow only
ADR-0003: confirm_fix asks the human through elicitation; the token never reaches the model
ADR-0004: this server is the auth and rate-limit boundary; static tokens now, OAuth later; refusals as tool results
ADR-0005: hosted as a Lambda behind API Gateway in stateless JSON mode, with a shared state key and tokens from Secrets Manager
ADR-0006:
start_investigationdeclares itself as FleetAlert'smcpentry point, so MCP-started rounds show as such in the Activity feedADR-0007: the server is its own OAuth 2.1 authorization server, stateless, with a consent page that signs in as
visitoror an operator key
License
MIT.
Available Tools
6 toolsget_activityBRead-onlyIdempotent
Recent cross-alert activity: end states, guardrail decisions, human confirm/reject actions and proposals, newest first.
Inputs: limit. Returns: count, events
get_alertARead-onlyIdempotent
One alert's current status and, once investigated, the proposed fix, the agent's confidence and its root-cause summary. For email- or detector-raised alerts, the inbound email or detection rule too.
Inputs: alert_id (required). Returns: `GET /demo/alerts/{id}/status`, minus the confirmation token.
get_raw_spansARead-onlyIdempotent
Raw trace spans for an alert, newest last, with full input and output. Large; prefer get_trace unless you need the detail.
Inputs: alert_id (required), kind, limit. Returns: spans, total, alert_id, returned
get_traceARead-onlyIdempotent
The investigation history of an alert, one entry per round: entry point, outcome, proposed fix, model calls, tokens, cost, and the ordered steps (model calls, capability calls, guardrail decisions, human actions). Use get_raw_spans for full inputs and outputs.
Inputs: alert_id (required). Returns: rounds, alert_id, span_count, total_cost_usd
get_usageARead-onlyIdempotent
Today's investigations and model spend against the demo's daily cost cap. When exhausted, action tools will be refused upstream.
Inputs: no named parameters. Returns: Today's spend against the demo's daily cost guard (FleetAlert ADR-0017).
list_alertsARead-onlyIdempotent
List every demo alert with its machine, severity and current status.
Statuses: open, queued, investigating, awaiting_confirmation,
resolved, rejected, routed_to_support, failed.
Inputs: no named parameters. Returns: count, alerts
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
The tools mostly target distinct needs: usage, alert listing, single alert summary, trace history, raw spans, and cross-alert activity. The main potential overlap is between get_trace and get_raw_spans, but the descriptions explicitly distinguish them by detail level and recommend get_trace by default.
All tools follow a clear verb_noun convention using get_ or list_ prefixes. The naming is predictable and readable throughout.
Six tools is well-scoped for an alert inspection/observability server. Each tool covers a distinct layer of information without excessive surface area.
Read-only inspection is well covered: alerts, investigation traces, raw spans, activity, and usage. However, the alert lifecycle includes statuses and human actions such as confirm/reject/resolve, but there are no action tools to mutate or progress an alert, which is a notable gap for the stated domain.
Maintenance
Related MCP Connectors
Read-only MCP server for AIStatusDashboard status, incidents, metrics, and fallback recommendations.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMCP server for the Production Master incident-investigation service, enabling any MCP client to drive investigations via tool calls with pass-through authentication.1MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server exposing scoped, read-only enterprise operations tools with fail-closed credential handling. It returns opaque approval IDs for mutations and requires a separate operator approval command to release one-time capabilities.MIT
- AlicenseNot gradedqualityCmaintenanceEnables production-hardened MCP tool serving with OAuth 2.1 audience-restricted tokens, purpose-bound tools, human-in-the-loop approvals, containment, and audit trails for AI agents.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients such as editors to start and monitor missions, run the self-healing demo, list departments and blueprints, and approve tasks through the backend API. It also lets trusted departments discover and invoke explicitly granted external stdio or Streamable HTTP tools.1MIT