Skip to main content
Glama
fleetalert-mcp

fleetalert-mcp

by mbgolden

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). get_trace turns dozens of raw spans into one summary per investigation round: what the agent read, what it proposed, what the guardrails decided, what it cost.

Safety tiers carried through the protocol

Tools are tagged read_only, proposes_action or executes_action, FleetAlert's own tier names. The server runs at one tier (default read-only) and tools above it are not registered at all, so a client cannot discover them. A bearer token carries a tier too, and can only narrow what the server allows.

Human approval, structurally

confirm_fix is the only tool that makes something execute upstream. It asks the human through MCP elicitation, in their own client, before anything is sent. The model passes an alert id and nothing else; the confirmation token is fetched by the server only after approval and never appears in a tool result. A client that cannot ask is refused.

The server is the auth boundary

Over Streamable HTTP, requests need a bearer token (401 with WWW-Authenticate and RFC 9728 protected-resource metadata otherwise). Static governor keys are compared by digest in constant time. The server is also its own OAuth 2.1 authorization server for clients that follow the MCP authorization spec (Claude Desktop, claude.ai): dynamic registration, PKCE, a consent page, refresh tokens, all without a database, because every record is sealed into the token that refers to it. stdio has no tokens: the process boundary is the auth boundary, as the spec intends.

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. /metrics reports calls, errors, tier refusals and rate limits per tool; /healthz reports version, tier and configured clients.

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 confirm_fix. A read-only smoke test runs against the live demo on demand and weekly.

Related MCP server: enterprise-mcp

Tools

Tool

Tier

What it does

list_alerts

read_only

Every demo alert with machine, severity and status

get_alert

read_only

One alert's status, proposed fix, confidence and root-cause summary

get_trace

read_only

Investigation history, one summary per round

get_raw_spans

read_only

Raw spans with full input and output, filterable by kind

get_usage

read_only

Today's spend against the daily cost guard

get_activity

read_only

Recent cross-alert activity feed

start_investigation

proposes_action

Start an agent round on an open alert (spends budget)

simulate_inbound_email

proposes_action

Deliver the demo's seeded maintenance email

run_telemetry_detector

proposes_action

Run the rule-based detector once

confirm_fix

executes_action

Ask the human, then confirm the proposed fix upstream

reject_fix

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-mcp

To 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-mcp

Claude 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

TIER

read_only

Highest tier of tool to register: read_only, proposes_action, executes_action

API_BASE_URL

the live demo

FleetAlert API base URL

TOKENS

empty

HTTP mode bearer tokens: client_id:tier:secret[,...], secrets 16+ chars

PUBLIC_URL

http://host:port

Public URL of this server in HTTP mode (for the protected-resource metadata)

ALLOW_ANONYMOUS_HTTP

false

Run HTTP mode without tokens, loopback only

STATE_KEY

unset

Fixed key (32+ characters) sealing elicitation state, and every OAuth record, across processes (required on Lambda)

OAUTH_ENABLED

false

Also serve an OAuth 2.1 authorization server (/authorize, /token, /register, /revoke, /consent); needs STATE_KEY

CALLS_PER_MINUTE

30

Per principal, every tool

ACTIONS_PER_HOUR

6

Per principal, tools above read_only

UPSTREAM_CALLS_PER_MINUTE

120

Across all principals

UPSTREAM_TIMEOUT_SECONDS

10

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 8000
  • POST /mcp is the MCP endpoint. Without a valid Authorization: Bearer header it answers 401 with a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource/mcp.

  • The ci token above sees every tool the server registers but is refused on anything above read_only, with a message the model can read.

  • GET /healthz and GET /metrics are unauthenticated and JSON.

  • With FLEETALERT_MCP_OAUTH_ENABLED=1 the 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

FLEETALERT_MCP_PUBLIC_URL

the API Gateway endpoint (issuer and resource for the bearer auth)

FLEETALERT_MCP_SECRET_ARN

a Secrets Manager secret holding {"tokens": "...", "state_key": "..."}

FLEETALERT_MCP_TIER

the server's tier; tokens narrow it per client

FLEETALERT_MCP_OAUTH_ENABLED

true to let Claude Desktop and claude.ai connect through OAuth

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_only

Nothing 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 demo

Run 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 them

Decisions

  • 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_investigation declares itself as FleetAlert's mcp entry point, so MCP-started rounds show as such in the Activity feed

  • ADR-0007: the server is its own OAuth 2.1 authorization server, stateless, with a consent page that signs in as visitor or an operator key

License

MIT.

Available Tools

6 tools
get_activityB
Read-onlyIdempotent

Recent cross-alert activity: end states, guardrail decisions, human confirm/reject actions and proposals, newest first.

Inputs: limit. Returns: count, events

get_alertA
Read-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_spansA
Read-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_traceA
Read-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_usageA
Read-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_alertsA
Read-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

    A3.8/5.0

    Scored across 6 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    All tools follow a clear verb_noun convention using get_ or list_ prefixes. The naming is predictable and readable throughout.

    Tool Count5/5

    Six tools is well-scoped for an alert inspection/observability server. Each tool covers a distinct layer of information without excessive surface area.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for the Production Master incident-investigation service, enabling any MCP client to drive investigations via tool calls with pass-through authentication.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      MIT