MCP configuration

This page describes Darling v3.13.0. The source of this page is on GitHub at that version.

Audience: operators.

This page covers the mcp block of darling.json. It moved here from the Darling operator guide. To turn MCP on and connect a client, see MCP server. For GitHub Copilot in VS Code, see GitHub Copilot in VS Code.

mcp

The embedded MCP server, over Streamable HTTP bound to localhost by default (see Opt-in Network Endpoints (LAN) to reach it — and the store — from the LAN). It exposes nearly all the tool names Lite exposes. It adds Darling-only reads (PostgreSQL, fleet, store). It also adds Darling-only write surfaces, each off until you turn on its switch: Custom Views management, alert tuning, server onboarding, collector control, quiet windows, query tags, agent actions and investigations. The default path (/) serves every tool; a client that only needs the fact-finding path can point at /core instead, a fixed subset of about 70-90 tools reachable from list_servers, get_fleet_overview, analyze_server and get_tool_guide by following each finding’s next_tools, served behind the exact same Host, token and CIDR checks as /:

  • Diagnostic-analysis tools — analyze_server, get_analysis_facts, compare_analysis, audit_config, get_analysis_findings, mute_analysis_finding, unmute_analysis_finding.

  • Plan-analysis tools — analyze_query_plan (by query_hash), analyze_procedure_plan (by sql_handle), analyze_query_store_plan (by database_name + query_id), analyze_plan_xml (raw showplan XML, no fetch), get_plan_xml (raw stored plan XML by query_hash), and the five raw-plan reads behind the web grids’ plan buttons: get_query_store_plan_xml (by database_name + query_id, optional plan_id), get_procedure_plan_xml (by sql_handle), get_active_query_plan_xml (by an Active Queries row’s collection_time + session_id, optional request_id, live), get_blocking_plan_xml (by a get_blocking row’s event_time and both spids, side=blocking for the blocker’s plan) and get_deadlock_plan_xml (by a get_deadlocks row’s collection_time and deadlock_time). get_query_repro_script builds a paste-ready T-SQL repro script from a stored query’s text and plan (kind = query_hash, query_store or active_snapshot, plus that kind’s key); store-only, nothing runs and no live plan is fetched. The analyze_* tools run the shared execution-plan analyzer over the plan XML the collectors already captured into the store — a stored-plan read, never a live query against the monitored server. analyze_query_plan/get_plan_xml accept an optional database_name, and analyze_query_store_plan an optional plan_id, to pin the exact stored plan when the caller knows it.

  • Core data-read tools — the diagnostic reads an assistant needs to investigate a server, each a stored read of the collected data (never a live query against the monitored server):

    • Resource metrics — get_cpu_utilization, get_wait_stats, get_wait_trend, get_wait_types (the distinct observed wait types, to pick one for get_wait_trend), get_memory_stats, get_memory_clerks, get_file_io_stats, get_tempdb_trend, get_perfmon_stats.
    • Query performance — get_top_queries_by_cpu, get_top_procedures_by_cpu, get_query_store_top, get_query_store_query_history (one query’s per-plan history behind the web grid’s History button; these hand back the query_hash / sql_handle / query_id + plan_id keys the plan-analysis tools consume).
    • Query Store clutter — get_query_store_clutter (#3797), composed from rows already collected rather than from a new query against the server: per database the query_store collector’s read cost (how often and by how much it was the slowest fan-out item, off collection_log‘s V80 rollup), plan churn (plan_id cardinality on the raw query_store_stats rows — plans per query at p95, arrivals per day, the one-shot fraction) and the newest query_store_health options row, each with raw numbers and a decomposed verdict; plus ONE per-server overhead block — the non-sleep QDS_* wait deltas with the four sleep waits IgnoredWaitDefaults drops named as excluded, and MEMORYCLERK_QUERYDISKSTORE. A database whose readonly_reason carries the readable-secondary bit is excluded by architecture with the reason on the row (a replica’s Query Store is its primary’s); query_capture_mode is the V137 (#3796) column read verbatim, with capture_mode_known beside it — a null there is a capture older than the rung, never NONE — and the churn recommendations name the mode (ALL beside churn is the switch-to-AUTO case, AUTO beside it points at the workload); fleet_median is opt-in because it walks two raw hypertables fleet-wide. The same rows reach the web server page’s Queries tab (one fetch, three panels: the per-database rows, the per-server wait block and the memory clerk) and the Viewer’s Queries → Query Store Clutter sub-tab, both reading the same statements and the same composition, so a verdict and a remedy are worded once.
    • Discovery / health — list_servers (with collection-freshness status, each row’s engine — engine_kind is the registry token, engine_version the engine-aware version label, and sql_version a deprecated alias of engine_version kept so existing consumers keep working — and the declared peer stores when the fleet is split across several Darling boxes), get_collection_health, get_server_properties.

    These are the tools the analysis findings’ next_tools recommendations point at, so a client following a finding’s advice resolves them on this same server. Result shapes match Lite’s (the store is Lite’s collector schema); where Lite and the Dashboard’s shapes diverge, Darling follows Lite — the shape its collector-mirror store can serve faithfully.

  • Diagnostic-depth data-read tools — deeper reads for a blocking / deadlock / session / configuration / storage investigation, each a stored read:

    • Blocking / deadlocks — get_blocking (blocked/blocking pairs from the blocked-process-report XE + the always-on DMV fallback), get_deadlocks, get_deadlock_detail (raw graph XML), get_blocked_process_xml (raw report XML), and the per-minute count series get_blocking_trend / get_deadlock_trend.
    • Sessions — get_session_stats (latest per-application connection counts), get_active_queries (captured running-query snapshots), get_waiting_tasks.
    • Config — the change history get_server_config_changes, get_database_config_changes, get_trace_flag_changes, plus the latest-snapshot pair get_database_scoped_config / get_query_store_health (per-database Query Store health: actual vs desired state, readonly_reason decoded, storage vs cap) and the current-config snapshots get_server_config / get_database_config / get_trace_flags (what sp_configure / sys.databases / the active trace flags are set to right now — the companion to the *_changes diffs, which are empty on a stable server).
    • Schema history (Darling-only) — get_object_definition (one table or view of a database: columns, indexes, constraints and triggers of the current version, or of the version that held at as_of; columns are paged and cut to the response budget, and a view’s text past 8 KB of JSON is cut on a text-element boundary with view_definition_truncated), get_schema_changes (the changes recorded in a window with the diff against the previous version, who made the change when the session named them, and include_baseline) and find_schema_objects (current objects by name, column, foreign key to a table, or the text of a view, computed column, default, check or index filter, which needs database_name and is refused at mcp.dataDetail maskLiterals and metadataOnly) (#7643). They read the history the schema_objects collector writes (off by default; not_collected until it has run for the server) and every role may call them. A database of an availability group is kept under the group, so any replica answers with the same history (resolved_from_ag). Names, types and structure are served at every data-detail level; the expression text is under masked keys.
    • Change watches (Darling-only) — get_change_watches lists a server’s change watches, open and closed, newest first (#6234). A recorded change (SQL Server: server, database or database-scoped configuration, a trace flag, a forced or unforced Query Store plan, a Query Store hint set, changed or cleared on SQL Server 2022 and later (#6581); PostgreSQL: a server setting, a per-database or per-role setting, an extension install, drop or version change) opens a 60 minute watch (changes are looked for once an hour per target, so a change is recorded up to an hour after it happened; the watch window still runs from the change itself, and a target whose watch is due is read once more before it is evaluated, so a later change inside the window still joins it); at its end Darling compares wait time per second, average CPU and query duration with the hour before and the same hour a week earlier, and opens one change_watch investigation request only if something moved. Each watch lists its changes, its measures and its result (flat, request_opened, moved_no_request, moved_agent_change, moved_auto_plan_correction, no_data) or its state (open, evaluating, closed, failed); state filters on any of those. A closed watch that measured many queries can run to about 20 KB, so ask for a small limit (3 to 5), or pass watch_id to read one watch in any state. measures, not_measured and changes are sent once, at the top of each watch, and result_detail holds the rest of the stored result. A PostgreSQL target with no source for a measure (no CPU samples, no wait collection, no statement statistics) lists it under not_measured with the reason, never as flat. A read of the monitoring store; the investigation agent may call it.
    • Known patterns (Darling-only) — get_known_patterns lists the entries an operator wrote about alerts that recur (#6334), such as “the backup job pushes High CPU every night at 02:00”: an optional server, alert metric and time of day (a wall-clock time in an IANA time zone, a window either side of it, wrapping past midnight), a note of at most 500 characters and an optional expiry. An empty scope means any. Every get_alert_history row carries known_patterns, the entries (id, note, created_by) that match it by server, metric, time of day in the entry’s zone and expiry at the alert’s time; [] means none matched. An entry is context only: it never mutes, pages or changes an alert, and its note is operator-written text to read, never an instruction. Entries live in config.config_known_patterns (V214) and are written through the owner-rights functions config.insert_known_pattern, update_known_pattern and delete_known_pattern, which provisioning grants to the viewer and admin roles only; no MCP tool writes them.
    • Index / object — get_table_index_sizes (size + growth), get_index_usage (Unused / Write-only / Active), get_object_locking (lock/latch contention), get_database_sizes.

    The three config-change tools diff the store’s config snapshots. This edition captures configuration when the service connects to a server (not on a fixed schedule), so a change is detected between two connect snapshots and at least two are needed — a stable, always-connected deployment may show no changes until the next connect. They emit only the values the collectors capture; the Dashboard’s requires_restart / setting description / setting_type / generated change-narrative enrichment is not collected here and is omitted. The Dashboard’s get_blocking_deadlock_stats aggregate is not hosted (Darling has no blocking/deadlock rollup table — use get_blocking / get_deadlocks for the raw events).

  • Resource-contention + jobs data-read tools — deeper reads for an internal-contention / worker-thread / plan-cache / SQL Agent investigation, each a stored read of the latest collected snapshot:

    • Latch / spinlock — get_latch_stats (top latch classes by wait time, per-second rates), get_spinlock_stats (top spinlocks by collisions).
    • Memory grants — get_resource_semaphore (workspace-memory target / max-target ceiling vs granted / used), get_memory_grants (per-pool grant detail), get_memory_pressure_events (RING_BUFFER_RESOURCE_MONITOR notifications — the process/system pressure indicators, not on Azure SQL DB).
    • Plan cache / scheduler — get_plan_cache_bloat (single-use vs multi-use + bloat level), get_cpu_scheduler_pressure (runnable queue, worker utilization, pressure level).
    • Jobs — get_running_jobs (running SQL Agent jobs vs historical average / p95).

    The Dashboard’s per-class latch severity / description / recommendation, spinlock description, plan-cache bloat_level, and CPU-scheduler pressure_level / recommendation are the Dashboard / reporting-view CASE derivations (not collected columns), reproduced service-side so the full result shape is served. Per-second latch/spinlock rates divide by each row’s stored sample_interval_seconds (the measured seconds its deltas accrued over, stored beside the deltas on every delta family since V128 — SQL Server and PostgreSQL alike) and are null rather than 0 when that interval was unknowable — a restart, not quiet. get_resource_semaphore emits the Dashboard’s sample_interval_seconds again now that the memory-grant collector stores it (V128), null with interval_known: false on a restart marker or a pre-V128 row; max_target_memory_mb, the workspace-memory ceiling, is added since the store carries it.

  • PostgreSQL data-read tools — the read surface for a PostgreSQL target’s collectors, each a stored read. The get_pg_* family is larger than the reads called out here (see PostgreSQL targets):

    • Waits and queries — get_pg_wait_stats (top wait events in the window, decoded to type + event name), get_pg_top_queries (query shapes by total execution time, carrying Aurora’s storage-vs-cache I/O split and per-statement peak memory).
    • Outage predictors — get_pg_wraparound_risk (XID and MultiXact freeze headroom per database), get_pg_xmin_horizon (why vacuum is reclaiming nothing, attributed to the specific holder), get_pg_replication_slots (slot health, including whether retained WAL is still growing).
    • Maintenance — get_pg_autovacuum_health (tables behind on vacuum or analyze, ranked by how far past each table’s OWN trigger threshold it is — the ratio, not the dead-tuple count, because the same count is routine on a large table and urgent on a small one).
    • I/O attribution — get_pg_io_stats (reads, hits, extends and evictions by backend type, object and context). The context dimension is the one with no SQL Server counterpart and the one that changes the remedy: it separates ordinary buffer-pool misses, where more shared_buffers or a better index helps, from sequential scans that deliberately bypass the pool through a small ring buffer, where neither will.
    • Per-database counters — get_pg_database_stats (temp-file spills, cache hit ratio, deadlocks, and the commit/rollback split, from pg_stat_database). Temp files are the reason it exists: they are work work_mem could not hold, which is the most common cause of a PostgreSQL query being slow for a reason its plan shape does not show, and on stock PostgreSQL it is the only temp-file evidence available anywhere. A statistics RESET is reported as a reset — an explicit count and a lower-bound caveat — rather than surfacing as a negative rate or a spike. Since V133 each row also carries peak_numbackends, the window’s peak of connected backends for that database — a level, never differenced, null on a pre-V133 history rather than 0 — deliberately not summed across databases (the peaks land at different instants); the max_connections fraction lives on the PG_CONNECTION_SATURATION fact, which sums at one instant.
    • Storage — get_pg_table_bloat (the per-table bloat ESTIMATE, suppressed rather than captioned when its statistics cannot be trusted) and get_pg_index_usage (per-index scan counts with the constraint, replica-identity and validity facts that decide whether an unscanned index can be dropped at all).
    • Sessions and contention — get_pg_blocking (blocking chains that were SAMPLED, with the root blocker attributed and both sides’ state captured — PostgreSQL has no engine-side blocked-process recorder, so blocking shorter than the interval leaves no trace anywhere) and get_pg_session_states (who is holding a transaction open, and whether they actually pin the xmin horizon). That second half is a different question from the first, and the tool exists to keep them apart: an idle in transaction session under READ COMMITTED that has only read, or whose write matched no rows, holds neither a snapshot nor a transaction id and starves vacuum of nothing — both measured on a live instance. So the read gates its causal claim on peak_horizon_age, where -1 means the session pinned NOTHING, and tells you so rather than letting a long duration imply otherwise. Pairs with get_pg_xmin_horizon, which names the CLASS of holder where this names the session.

    These are separate tools rather than widened SQL Server ones. PostgreSQL’s waits are a two-level type/event taxonomy with no signal-wait concept reported in microseconds, and the wraparound / horizon / slot signals have no SQL Server counterpart at all — sharing a result shape would mean lying about a unit or emitting mostly-null columns. The three outage predictors are the ones worth wiring to a pager: each names a condition that stops the server outright, and each is silent until it is nearly too late.

  • Trend data-read tools — windowed time-series siblings of the core reads, each a stored read of the collected series over the window (BOTH-sides, naive-UTC):

    • get_memory_trend (total / target server memory, buffer pool, plan cache over time), get_perfmon_trend (a single counter’s value + delta, counter_name required), get_file_io_trend (read/write latency per database and file type, the five with the most I/O stall plus one (other) line; database_name for one database per file), get_query_trend (one query’s per-collection history by query_hash + database_name), get_query_duration_trend (overall elapsed-ms/sec + executions/sec).

    Each mirrors the viewer’s proven chart read (byte-identical Postgres SQL); the shape follows Lite where the SKUs diverge. get_perfmon_trend reproduces Lite’s miss vocabulary (Page Life Expectancy is intentionally not collected; an unknown counter hands back the collected names). get_memory_trend carries a total_granted_mb field for field-for-field parity with Lite, joined per point from the memory-grant series (the same v_memory_grant_stats sum the viewer’s overlay charts plot) — a point no grants snapshot covers within 30 seconds stays an explicit null, with a granted_note naming get_memory_grants, never a fabricated 0 (#3529, #3548).

  • System-health parse-on-read tools — the Dashboard’s get_health_parser_* family, over Darling’s raw system_health_events:

    • get_health_parser_system_health (corruption + contention counters), get_health_parser_severe_errors (severity ≥ 19, with database_id resolved to a name), get_health_parser_scheduler_issues, get_health_parser_memory_conditions, get_health_parser_memory_broker, get_health_parser_memory_node_oom, get_health_parser_cpu_tasks, get_health_parser_io_issues.

    Where the Dashboard reads its server-side-parsed collect.HealthParser_* tables, these shred the raw extended-event XML on read with the shared SystemHealthParser (the same parser the viewer’s System Events tab uses) and gate with the service-side twin of the viewer’s SystemEventSignificance — returning the same SIGNIFICANT warning set the Dashboard surfaces (sp_HealthParser at @warnings_only = 1). get_health_parser_system_health is the one UNGATED category (its counter series plots every snapshot). Each row carries the full sp_HealthParser column set keyed on the event’s event_time; the tools window on event_time (the event’s real time), so “last 24 hours” means events that happened in the last 24 hours.

  • Tool reading guides – get_tool_guide(tools, topics) (#3898, both editions). A converted tool’s description is split at a <<GUIDE>> marker: tools/list serves the short head, which keeps every fact needed to read the answer correctly and ends “Reading guide: get_tool_guide.”, and this tool returns the long-form guide by tool name, plus named cross-tool topics such as system_health_empty_windows. Unknown names are reported, not errors; called with no arguments it lists the tools that have guides and the topics. The get_health_parser_* family is converted first.

  • Alert + health-overview tools — the fleet-triage reads the fleet edition previously lacked, each a stored read over the monitoring store (no live hit):

    • Alerts — get_alert_history (what fired, value vs threshold, delivery success/failure, muted, and since V131 route — where the post went — fleet-wide by default, or scoped to a server; external_source names the external alert source an alert came from and is null on every built-in and custom alert), get_alert_settings (the current alert config the service is using — per-alert enable/thresholds, cooldown, excluded databases, delivery mode, analysis cadence), get_mute_rules (the alert mute rules in force, so a suppressed server is distinguishable from a healthy-quiet one; each rule carries external_source, null unless the rule is limited to one external alert source), get_notification_routes (the alert-family taxonomy and the notification routes — which channels each route sets and its severities, never the destination values).
    • Health overview — get_server_summary (one-shot per-server CPU / memory / recent blocking / recent deadlocks), get_daily_summary (a day’s composite health band — Healthy / Warning / Critical — folded through the shared DailyHealthBandCalculator, plus the signals behind it).
  • Fleet sweep reports (Darling-only) — get_sweep_reports reads the scheduled Fleet Sweep Reports — the stateful whole-fleet summaries the service persists at the configured cadence (get_alert_settings‘ fleet_sweep group; default hourly): the sweep timeline over a caller-set window with each sweep’s document embedded, except the newest sweep’s, which rides once under latest while its entry keeps the row counts and says report_under: latest, the newest sweep in full (per-server verdicts with band transitions pre-computed, and the would-have-paged ledger whenever a sweep ran under the alert master switch — present-and-empty on a muted sweep with nothing to report, ABSENT on an alerts-on sweep where no such check was made), and the watch-item worklist with its hysteresis position. One sweep_id (as a STRING — the ids are too large for a JSON number to round-trip) fetches one sweep in full. The same FleetSweepPresentation builders and store reads the web feed’s /api/sweeps routes serve, so an agent and a browser cannot disagree about what a sweep looks like. The description carries the two field contracts an agent must read: alerts_enabled: false on a sweep means DELIVERY WAS OFF while it ran, and instruments_alive: false means the sweep could not prove its own data sources — quiet is not clean, and the instrument_liveness block says which instrument went unproven. A stored read; no monitored server is touched.

  • Daily Health Report (Darling-only, #7041) – get_daily_health_report builds the report for one day from the monitoring store and sends nothing, so an agent or a person can preview it. The optional date is a local date (yyyy-MM-dd) in the report’s time zone. The period is the 24 hours that end at that date’s send time. Without date you get the latest finished period. A date whose send time is still ahead is refused. The answer holds the subject, the short text that Slack, Teams and the webhook receive, the period start and end in UTC, a summary (servers by band and alerts fired) and the servers worst first. Each server carries its band and reasons, its alerts (a count per metric), failed Agent jobs, databases past the backup or CHECKDB bars, low disk volumes and collection problems. Failed jobs, database protection and low disk are SQL Server only. The band is the fleet overview card’s 24-hour band. Collection problems and database protection are read as the store holds them when the report is built, so for an earlier date they are today’s. The report’s own delivery row is left out of the alerts count. send_daily_health_report_now is a write tool. It is served when mcp.allowWrites is on, or to a named operator token, and is never offered to an investigation agent. It builds the report for the 24 hours that ended at the most recent send time. It sends the report through the Daily Health Report metric of the reports family, to the destinations a notification route for that family or metric chooses. It does not touch the once-a-day record. The scheduled report still goes out, so a recipient can get two. It works while daily_report.enabled is off, and it is refused (alerts_disabled) while the alert master switch is off. Its answer says what the alert pipeline reported: sent, muted, unconfigured when no channel is set up, or failed. The schedule itself is the daily_report group of get_alert_settings and update_alert_settings (enabled, send_at as "HH:mm", time_zone where null is the service host’s zone, and title where null is Daily Health Report). See Daily Health Report.

  • Custom Views tools (Darling-only) — discover, create, and manage the saved dashboards/notebooks a user composes from the curated measure catalog (the same views the web viewer’s editor builds), stored in config.custom_views. None touches a monitored SQL Server or the collected performance data — the write tools write only view definitions to the monitoring store.

    • Discover — describe_custom_view_catalog (the compose vocabulary — measures with their source/kind/valid-aggregates/allowed-dimensions/units/per-server-type availability, dimensions, unit families, aggregates, time buckets, filter ops, and viz types). An MCP client calls this FIRST so a composed panel uses only legal identifiers instead of guessing at names; it returns the SAME /api/catalog vocabulary the web composer’s picker binds to. Read-only static reference — no store, no server.
    • Read — list_custom_views (summaries: id, name, description, kind, folder, personal, created_by, version, updated_by; an optional folder argument lists one folder, and an empty string lists the top level; every personal view is listed, marked personal: true), get_custom_view (one view’s full definition + version).
    • Author — validate_custom_view (dry-run a definition against the catalog + composer rules, no save), create_custom_view (validate then save; takes an optional folder), update_custom_view (validate then replace in place, optimistic-concurrency on version; folder omitted keeps the current one), delete_custom_view. Over MCP a view is always shared, never personal, because MCP has no person identity, and a personal view cannot be updated or deleted over MCP (it answers refused): only its owner can change it, in the web dashboard.
    • Self-test — run_custom_view_panel (compile + run a single composed panel and return {sql, rows, annotations} — the composer’s live preview, for checking a generated panel’s data before saving).

    The create/update/delete tools are the one view-authoring write surface; create/update run the SAME ValidateDefinition authority as validate_custom_view, so an invalid definition is rejected before it stores; every tool routes through the SAME store + validator + compile-and-run + catalog the web viewer’s editor uses (no divergent second implementation). This write surface is part of what the MCP token gates — see What a token can reach below.

  • Alert-tuning write tools (Darling-only) — update_alert_settings, create_mute_rule, update_mute_rule, delete_mute_rule, purge_expired_mute_rules (deletes every expired rule, as the Viewer’s Purge Expired does, and returns each one it deleted with undo: null because an expired rule had no effect), set_mute_rule_enabled, and the route writes create_notification_route / update_notification_route / set_notification_route_enabled / set_notification_route_fallback / delete_notification_route (update_notification_route also sets a route’s action_approval and approval_single_person, and it can only tighten them: see Level 3 server actions: approval), and update_notification_channels (the default channels the Viewer sets in Settings > Notifications: SMTP host, port, SSL, user, password, from and recipients; the Teams, Slack and generic webhook URLs, the generic headers, body template and proxies; the PagerDuty routing key, region, proxy and auto-resolve. Only the fields passed change and - clears a text field. Each secret is sealed by the service the way the Viewer seals it and is shown in an answer only as set or not set; the mcp role holds no read or write on a secret column and writes them through the store’s config.set_notification_channels function, which makes the Viewer’s refusals on the stored row (a change to the host, port, SSL flag, user or a proxy while a secret tied to it is saved needs the secret again; a saved signing key blocks a generic URL or proxy change). The undo restores only the non-secret settings.) (both route tools set a route’s own destinations: Teams, Slack and generic webhook URLs, a PagerDuty routing key and email recipients, sealed for the route’s own row and shown in an answer only as saved or none (with the host for Teams and Slack), apart from the recipient list, which is shown in full; create_notification_route takes the same severities word (default both, so a route takes alerts of both severities unless you limit it, and any other value is refused as invalid), and with no destination makes a route with every channel empty, so each channel goes where it went before (the next matching route, else the channels configured in Settings); update_notification_route changes the match, scope, enabled flag, resolution override, severity filter (severities: critical, warning or both), fallback and destinations of any route that is not an agent route, and the match or scope only on a route with no explicit agent setting (a route with an agent setting of Off keeps its match and scope in the Viewer, and the store function refuses the change for any login); both refuse an agent route, and the answer of an edit gives the previous values and the undo call, which for a destination says to pass the earlier value again. Each write is logged with the tool, the identity the service knows for the token (its first 8 SHA-256 hex characters, never the token), the client’s own name labelled client says (any client can send any name) and the names of the fields changed, never a value), plus dismiss_alert_history / restore_alert_history (the flag the web dashboard’s Dismiss sets, and the call that undoes it; nothing is deleted). None of these is callable by an agent Darling sends to investigate an alert let an MCP client TUNE the alert engine the fleet shares (create_mute_rule / update_mute_rule also take an optional lower-case external_source that limits a rule to the alerts one external source raised; a name that is not a valid source name is refused, and update_mute_rule clears it with an explicit null) — the SAME config get_alert_settings / get_mute_rules read and the Viewer’s Settings window writes. update_alert_settings is a PARTIAL update of the alert configuration: read via get_alert_settings, change fields, and send only those back in the same nested shape; every field is validated against the SAME ranges/enums the Settings window enforces BEFORE any write, an out-of-range or unknown field returns {status:"invalid"} and writes nothing, and the write self-bumps config_version so the running service hot-reloads within one collection sweep. create_mute_rule / update_mute_rule / delete_mute_rule / set_mute_rule_enabled reuse the SAME PgMuteRuleStore get_mute_rules reads through (and the same GUID id-generation the Viewer’s mute-create path uses). set_mute_rule_enabled is the headless twin of the Viewer’s mute-rule checkbox: it writes enabled and nothing else, so a rule can leave force and return keeping its id, its reason and the created_at_utc the Stale Mute Rules self-alert ages it from — where a delete-and-re-create resets that clock and delivers the suppressed alerts in between. update_mute_rule is the headless twin of the Viewer’s Edit dialog on the same terms: a PARTIAL update (send only the fields to change, in the shape get_mute_rules returns; an explicit JSON null clears a field, so a bounded rule can be made permanent again) written through the store’s own full-row UpdateAsync — whose SET list does not name created_at_utc, so no edit, however sweeping, resets the staleness clock the way the delete/recreate workaround did for every field the enable flag cannot express. update_alert_settings spans the two singleton config rows the alert engine reads: every knob is on config_alert_settings except the per-fingerprint DELIVERY cooldown, which is stored as config_notification.email_cooldown_minutes and reported and accepted as delivery.cooldown_minutes — a channel-neutral name, because that one number is the only throttle on a Slack / Teams / PagerDuty / generic-webhook post as well as on email, so a headless deployment with no SMTP configured at all is still governed by it (the stored spelling is accepted as a write-only alias). Note the two cooldowns are different stages: top-level cooldown_minutes gates whether the engine FIRES, delivery.cooldown_minutes bounds the resulting post — twice over, once per alert FINGERPRINT and once per METRIC across the whole fleet for a RE-notification, so one fault on forty servers does not cost forty posts an hour and the servers that second bound holds back are named on the post that does go out. A first notice is never held back by either bound, and delivery.mode PerEvent opts out of the per-metric one. None touches a monitored SQL Server or the collected data — only the shared alert configuration; the one tool that sets delivery credentials is update_notification_channels, which sets the SMTP password, the webhook URLs and the keys sealed and never shows them back (the mcp role itself can read and write exactly the one non-secret cooldown column of the notification table and cannot read or write any secret column; the sealed values reach the store through the config.set_notification_channels function). It is part of what the MCP token gates — see What a token can reach below.

  • Recurring mute rules (Darling-only, #7040): create_mute_rule and update_mute_rule take an optional schedule. recur_days is a list of day names (Mon or Monday, any case) and is omitted for every day. recur_start and recur_end are HH:mm and go together. recur_time_zone is an IANA id, or a Windows id the service converts, and defaults to the service host’s zone when times are given with none. The rule mutes only inside the daily window, and only between its start and expiry. A window that ends before it starts crosses midnight and belongs to the day it starts. To clear a schedule, send recur_start and recur_end as null to update_mute_rule, and the days and zone clear with them. get_mute_rules returns recur_days, recur_start_time, recur_end_time and recur_time_zone on each rule, plus schedule (one line of text), in_window_now and next_window_start_utc. A rule with no times is a one-off rule.

  • Webhook signing key tools (Darling-only, #6394) — generate_webhook_signing_key and remove_webhook_signing_key, each with an optional route_id (none is the default destination’s key in Settings > Notifications, a number is that route’s own generic webhook). generate_webhook_signing_key makes the key in the service, seals it for the destination’s saved generic URL and proxy as the Viewer does, and stores it through the store’s config.set_webhook_signing_key function; the mcp role has no read or write on a signing key column, and the service reads the saved URL and proxy on its own store connection. When a key is already stored the call rotates it: the current key moves to the previous slot and keeps signing for 7 days. The answer shows the new key once, and no answer ever shows a stored or previous key; the key goes only over TLS or to a caller on the service’s machine, and a second generate inside the 7 day changeover of the first is refused unless the call passes replace_pending_rotation: true. A destination with no saved generic webhook URL, and a route_id that does not exist, are refused and write nothing. remove_webhook_signing_key clears the key, the previous key and the window, and says whether a key was there. Both are write tools, never offered to an agent token. update_notification_route refuses to change the generic URL of a route that has a key until the key is removed.

  • Server-onboarding write tools (Darling-only) — add_servers (BULK) and remove_server (which drops this install’s own Extended Events sessions on the server, the schema-changes one included, and leaves the shared ones: PerformanceMonitor_Deadlock, PerformanceMonitor_BlockedProcess, PerformanceMonitor_Attention and the old PerformanceMonitor_LongQueryCompletions; once the server is removed, --drop-xe-sessions --print-sql prints the statements that drop what is left, because the named form --drop-xe-sessions <server> works only before the removal) let an MCP client stand up or tear down FLEET monitoring conversationally (“monitor these twenty servers with this login”), the service-side twin of the Viewer’s Add / Manage Servers dialogs. edit_server changes one saved server in place and is served under the same mcp.allowServerAdmin setting as add_servers and remove_server; an edit that points Windows authentication at a connection whose server identity is not verified is refused as add_servers refuses it, before any connection is made. add_servers takes a JSON array of server objects (host required; optional display_name / database / read_only_intent / multi_subnet_failover; auth Windows/SQL with username+password for SQL; and the exposed TLS options encrypt_mode Optional/Mandatory/Strict + trust_server_certificate) and processes them in order: it validates each entry, PROBES the connection in-process (reusing the same DarlingServerConnector.ProbeAsync the --test-connection verb runs — the service holds the network path + credentials, so no test_connect command plane is needed), skips a case-folded duplicate (duplicate) of an already-monitored server or an earlier entry, DPAPI-encrypts the SQL password (the service identity, so it round-trips at collection time), and INSERTs the row mirroring the service’s own seed shape. A server that fails to connect is connection_failed and the batch continues. auth also takes the two non-interactive Microsoft Entra modes (#3484). With ServicePrincipal, username is the app’s client id and password is its client secret. The other mode is ManagedIdentity. Only the interactive Entra modes (MFA, device code, default credential) are invalid, because they need a signed-in user and cannot run headless. Off Windows, a literal SQL password or client secret is refused as invalid too, because encryption at rest is Windows DPAPI. Give an env:NAME or file:/run/secrets/<name> reference instead, the same two forms that darling.json takes for every secret. A server is refused as collides when its probed connection lands in a database that another monitored server already covers. That happens when it names one database but connects to a different one, such as a wrong Initial Catalog. Adding it gives one database two identities, so its history is stored twice and its alerts fire twice. A server whose id is already held by a different server is refused as collides as well, because two identities can hash to one id. Nothing is written for a collides entry. If saving an entry fails, that entry and every entry after it are not_saved and are not probed. The entries before it stay added. remove_server DELETEs a monitored server by name (resolved the same way every server_name is) — already-collected history is kept. Both write only the monitoring store’s config.config_monitored_servers registry; neither runs anything on a monitored server beyond the one-time probe. The SQL password travels to the endpoint inside add_servers‘ request and is DPAPI-encrypted at rest (never returned) — it is part of what the MCP token gates, and it puts a credential on the wire; see What a token can reach below.

Key Default Notes
enabled false Off by default — a headless service does not open a local port unless you ask
port 5152 Chosen so all three editions coexist on one machine (Dashboard 5150, Lite 5151)
allowTokenlessLoopback false On, a loopback-only MCP server with no token serves local clients without one, with the write and investigation tools off, and every start logs a line saying so. Off, an enabled MCP server with no token does not start. The setting applies only when no token is configured: a configured token is still read and gates every request, and a token that clears the floor (at least 16 characters, with at least 6 different ones) serves the write and investigation tools as allowWrites and allowInvestigations say. (Lite’s mcp_allow_tokenless_loopback differs: on, Lite does not read its stored token and serves reads only.)
allowWrites false Serves the MCP tools that change the monitoring store’s configuration, such as alert settings and notification routes, mute rules, custom alert rules and Custom Views. This is the legacy token’s switch: a named operator token in tokens is served the write tools with allowWrites off. Served only with a bearer token that is at least 16 characters with at least 6 different ones, and every request must then present it, loopback included. File-only: edit darling.json and restart. See MCP server.
allowServerAdmin false Also serves add_servers, edit_server, remove_server and set_server_action, which change which servers the service connects to, or where, as its own account. No effect while allowWrites is off. File-only and restart-only.
allowInvestigations false Serves claim_investigation_request, submit_investigation_report and post_investigation_message to your own agent (#5632). They write investigation state. The same setting serves the 16 Level 2 agent action tools: each call needs an agent_action argument and a live claim, and agent_actions_enabled (default on). The 9 store actions need a Level 2 route. The 7 server actions (kill_session, force_query_store_plan, unforce_query_store_plan, evict_cached_plan, recompile_module, create_plan_guide and drop_plan_guide) need a Level 3 request, the server’s own action switch (default off) and a remediation login reference. Served only with a bearer token (network.encryptedToken or network.token) and while allowWrites is off: one token cannot tell an agent from a person, so with both on they stay off and the start logs one Critical line. A named agent token in tokens is served them with allowInvestigations off. The reads list_investigation_requests, get_investigation_reports, get_investigation_evidence and wait_for_investigation_requests need no setting.
allowAgentMuteRules true With allowInvestigations on, lets an agent token create, change, enable, disable and delete a mute or digest rule with no claim (#7414): a named metric (a digest on one server or all servers, a mute on one server and never on one of the service’s own alerts), expiring within 7 days of creation, with a reason, every write journaled. The token is a named agent token or the unnamed token, which the journal records as legacy-token. Each agent can make 20 of these writes an hour, and cannot repeat a rule with the same metric, server and action within 14 days. Set false to refuse those calls (the refusal names this setting). The claim-based Level 2 and 3 tools are not affected. File-only and restart-only.
allowWindowsAuthOverUnverifiedTls false add_servers defaults to Windows authentication, where the service presents its own computer account to the host the caller names. Off, add_servers refuses a Windows-authentication entry that also sets trust_server_certificate or an encrypt_mode other than Mandatory or Strict, because the service could not confirm which server it reached. On, it accepts them. SQL authentication and the Entra modes are not affected. The --add-server command is not gated. The web dashboard’s add and edit have their own setting, web.allowWindowsAuthOverUnverifiedTls. edit_server is gated like add_servers: an edit that points Windows authentication at an unverified connection is refused. No effect unless allowServerAdmin is on. File-only and restart-only.
tokens none Named bearer tokens with a role (#6542): a list of { "name", "encryptedToken" or "token", "role", "dataDetail" }, where role is operator, agent or reader and dataDetail is optional. One service then serves an operator, its investigation agents and read-only users at once. An operator token sees the reads and the write tools, whatever allowWrites says, and never the claim or submit tools. It sees the four server admin tools (add_servers, edit_server, remove_server and set_server_action) only when mcp.allowWrites and mcp.allowServerAdmin are both on, the same rule the legacy token follows. An agent token sees the reads, the investigation tools and the Level 2 action tools, whatever allowInvestigations says, and never a never-agent tool. Its agent_id must be the token’s name. A reader token sees the reads and nothing else: no write tool, no server admin tool, no investigation tool and no Level 2 action tool, whatever allowWrites, allowServerAdmin and allowInvestigations say. A reader is not an agent and has no identity in the journal. A token’s dataDetail (full, maskLiterals or metadataOnly) can only narrow the service’s dataDetail: the token is served the stricter of the two, and an entry with no dataDetail is served the service’s level. An unknown dataDetail leaves that token unserved. For example, { "name": "dev-a", "token": "file:/run/secrets/darling/mcp-dev-a", "role": "reader", "dataDetail": "maskLiterals" } gives a developer the reads with literal values replaced while the operator keeps full. Behind a front door the same holds: the front door sends its caller’s level to the store, and the store serves the stricter of that and its own. A key in a token entry that is not a field (for example data_detail) is reported at start like any other unknown key. analyze_server with no as_of saves its findings to the store for every token, a reader included, as the legacy read-only token always has. Each name and each value is used once, and every request, loopback included, must present a token. The legacy network token keeps working as before. Read once at start. See Named tokens.
network none The token and the opt-in network exposure of the MCP server: listen, allowFrom, encryptedToken or token, and tls. The tls block takes a PFX file, a PEM pair or an entry in the Windows certificate store. With no network block, the server listens on loopback only. The token gates the loopback listener too. listen and allowFrom work in managed mode or the compose container, and are ignored with your own PostgreSQL outside the container. File-only. See MCP endpoint.
dataDetail full How much collected text every MCP tool answer carries. A named token can ask for less with its own dataDetail, never more (see tokens). full changes nothing. maskLiterals keeps query text but replaces its literal values (numbers, strings, parameter values) with ?. metadataOnly holds back query text, plan XML and input buffers, and masks login and host names (see below); object and database names, counts, durations, waits and times stay. An unknown value is read as metadataOnly. A tool’s own status sentence (the message beside status, for example the step a precondition asks for) stays readable at both levels, with its literal values replaced; under metadataOnly a login or client address it quotes from the monitored server’s own error text is replaced by the same pseudonym the rest of the answer uses. An investigation brief is composed at the same level (#5632). A login or host keeps one pseudonym (#6066): under metadataOnly a name is shown as login# or host# plus 8 hex characters of a keyed hash (login#3fa9c2d1), the same in every answer, brief, journal read and webhook from one store, across calls, sessions and service restarts. Case is ignored (CORP\alice and corp\alice read the same) and a login and a host with the same text differ. If two different names in one answer hash alike, the second gets -2. The key is 32 random bytes made by migration V198 in config.pseudonym_key; no role but the store owner can read it, the service reads it once and keeps it in memory, and no tool, log line, journal row, brief, webhook or export carries it. A copied or restored store keeps its key, so its pseudonyms stay the same; the key is never rotated. If the service cannot read the key, an answer numbers names per answer (login#1) and still hides every name. Briefs claimed before this release keep their per-brief numbers. On a bring-your-own store with no postgres.mcpConnectionString, the MCP connection falls back to the store owner and can read the key table, the same exposure password_key has there; no MCP tool runs caller-written SQL over that connection (every tool builds its statements from fixed text and bound parameters)

A token is required on loopback too. Once mcp.enabled is on, the MCP server starts only with a bearer token. Set mcp.network.encryptedToken (from --encrypt-password) or mcp.network.token (the token itself, env:NAME or file:PATH), and leave mcp.network.listen out to stay loopback-only. On Windows, use encryptedToken. env:NAME and file:PATH references are for the compose and Linux setups, where there is no DPAPI. To make a token, use the PowerShell one-liner under MCP endpoint. With no token the server does not start, and the service log names these settings. --print-mcp-token, run elevated on the service host, prints the configured token. To serve local clients with no token, as earlier builds did, set mcp.allowTokenlessLoopback to true. The write and investigation tools then stay off, and every start logs a line saying so.

Register with Claude Code, sending the token as a header:

claude mcp add --transport http --scope user sql-monitor-darling http://localhost:5152/ --header "Authorization: Bearer <token>"

In a project’s .mcp.json, read the token from an environment variable, because project files get committed:

{ "mcpServers": { "sql-monitor-darling": { "type": "http", "url": "http://localhost:5152/", "headers": { "Authorization": "Bearer ${DARLING_MCP_TOKEN}" } } } }

Set DARLING_MCP_TOKEN in the environment that starts Claude Code, or keep the token in the user-scope entry above.

If mcp.network.tls is set and mcp.network.listen is 0.0.0.0 or ::, the one MCP listener serves HTTPS to everyone, loopback included. Local clients then need https://, and the certificate must name the host they use. With a specific listen IP the loopback listeners stay plain HTTP, and the command above still works.

mcp.network.tls can name a certificate in the Windows certificate store instead of a file. Use "tls": { "store": { "thumbprint": "..." } }, or use "subject": "darling.example.com" to serve the newest valid certificate for that name. location defaults to LocalMachine and name defaults to My. Give one form only.

The service account needs Read on the key. Use certlm.msc (All Tasks, Manage Private Keys), or run PerformanceMonitor.Darling.Service.exe --grant-cert-key-access <thumbprint> from an elevated prompt. The service reads the certificate at start, so restart it after a renewal. The MCP TLS Certificate Expiring alert catches a restart that you missed. A store certificate that cannot be used keeps MCP loopback-only and logs a Critical line. Certificate from the Windows certificate store has the selectors, the key access step and every failure.

If the port is already in use at startup, the MCP server logs an error and does not start; collection is unaffected.

The store argument (front door only). On a service that runs as a front door, every tool also takes an optional store argument that names one of the front door’s stores. A store itself has no store argument. The front door sends a call to a store by store, then by server_name, then by the kind of tool, and it answers a read that names no server from every store. See How MCP calls route.