Skip to main content

Model Context Protocol (MCP)

Lumetry provides a tenant-scoped Model Context Protocol server for AI-assisted incident investigation. It exposes live operational context as structured, read-only tools without giving the client database access or a separate authorization model.

Connect​

Use your Tenant API host with the /mcp path:

https://api.example.com/mcp

The server uses the Streamable HTTP transport and requires a Bearer token. You can use a signed-in user's access token or, for durable automation, a dedicated Lumetry API token:

Authorization: Bearer {token}

Create the API token with only the permissions the client needs:

  • CanViewAlerts exposes operational overview, alert, and incident tools.
  • CanViewTelemetry exposes metric-series and topology tools.

The server omits tools the token cannot use and rejects direct calls that lack the required permission. API-token permissions are the snapshot selected when the token is issued. Never put a token directly in a committed configuration file.

Available tools​

ToolPurposeBound
lumetry_get_operational_overviewCurrent KPIs, priority open alerts, recent incidents, and topology totals.Defaults to 2 hours; maximum 31 days.
lumetry_list_alertsFilter alerts by metric, rule, severity, status, incident, and UTC range.Maximum 200 rows.
lumetry_list_incidentsFilter correlated incidents by status, severity, service/CI, and UTC range.Maximum 200 rows and 92 days.
lumetry_get_incident_contextIncident details, linked alerts, metrics, timeline, and optional forensic evidence.Maximum 200 rows per section.
lumetry_search_metricsSearch the active metric catalog.Maximum page size 100.
lumetry_query_metric_seriesRead an exact metric series with optional label scope.Maximum 24 hours and 2,000 returned points.
lumetry_search_topologySearch nodes by identity, name, hostname, owner, type, or environment.Maximum 200 rows.
lumetry_get_topology_contextTraverse relationships around one node to explain dependencies and impact.1–3 hops and maximum 200 nodes.

Alert, incident, and topology searches report hasMore when another matching row exists beyond their bound. Incident sections and graph traversals report truncated; metric-series results report sampled and the original point count when Lumetry evenly reduces a large series while preserving its first and last points. Narrow the UTC window, filters, label scope, or graph depth before making claims that require complete data.

Codex example​

Store the token in LUMETRY_MCP_TOKEN, then add this to a trusted project's .codex/config.toml or your global Codex configuration:

[mcp_servers.lumetry]
url = "https://api.example.com/mcp"
bearer_token_env_var = "LUMETRY_MCP_TOKEN"
default_tools_approval_mode = "writes"
tool_timeout_sec = 60

Restart the client after changing MCP configuration. Every current Lumetry tool declares itself read-only; writes mode preserves a confirmation boundary if write tools are introduced later.

  1. Start with the operational overview.
  2. Narrow the current state to alerts or incidents.
  3. Read the incident context before requesting raw telemetry; include evidence only when needed.
  4. Use topology context to explain containment, dependencies, likely cause, and service impact.
  5. Search for the exact metric before querying its series, then refine sampled results.

MCP version 1 cannot acknowledge, close, resolve, create, update, or delete Lumetry state. Use the documented REST commands and their normal audit/permission controls for those actions.