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(byquery_hash),analyze_procedure_plan(bysql_handle),analyze_query_store_plan(bydatabase_name+query_id),analyze_plan_xml(raw showplan XML, no fetch),get_plan_xml(raw stored plan XML byquery_hash), and the five raw-plan reads behind the web grids’ plan buttons:get_query_store_plan_xml(bydatabase_name+query_id, optionalplan_id),get_procedure_plan_xml(bysql_handle),get_active_query_plan_xml(by an Active Queries row’scollection_time+session_id, optionalrequest_id,live),get_blocking_plan_xml(by aget_blockingrow’sevent_timeand both spids,side=blockingfor the blocker’s plan) andget_deadlock_plan_xml(by aget_deadlocksrow’scollection_timeanddeadlock_time).get_query_repro_scriptbuilds a paste-ready T-SQL repro script from a stored query’s text and plan (kind=query_hash,query_storeoractive_snapshot, plus that kind’s key); store-only, nothing runs and no live plan is fetched. Theanalyze_*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_xmlaccept an optionaldatabase_name, andanalyze_query_store_planan optionalplan_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 forget_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 thequery_hash/sql_handle/query_id+plan_idkeys 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 thequery_storecollector’s read cost (how often and by how much it was the slowest fan-out item, offcollection_log‘s V80 rollup), plan churn (plan_idcardinality on the rawquery_store_statsrows — plans per query at p95, arrivals per day, the one-shot fraction) and the newestquery_store_healthoptions row, each with raw numbers and a decomposedverdict; plus ONE per-server overhead block — the non-sleepQDS_*wait deltas with the four sleep waitsIgnoredWaitDefaultsdrops named as excluded, andMEMORYCLERK_QUERYDISKSTORE. A database whosereadonly_reasoncarries 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_modeis the V137 (#3796) column read verbatim, withcapture_mode_knownbeside it — a null there is a capture older than the rung, neverNONE— and the churn recommendations name the mode (ALLbeside churn is the switch-to-AUTOcase,AUTObeside it points at the workload);fleet_medianis 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_kindis the registry token,engine_versionthe engine-aware version label, andsql_versiona deprecated alias ofengine_versionkept 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_toolsrecommendations 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. - Resource metrics —
-
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 seriesget_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 pairget_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 snapshotsget_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*_changesdiffs, 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 atas_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 withview_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, andinclude_baseline) andfind_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 needsdatabase_nameand is refused atmcp.dataDetailmaskLiteralsandmetadataOnly) (#7643). They read the history theschema_objectscollector writes (off by default;not_collecteduntil 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_watcheslists 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 onechange_watchinvestigation 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);statefilters on any of those. A closed watch that measured many queries can run to about 20 KB, so ask for a smalllimit(3 to 5), or passwatch_idto read one watch in any state.measures,not_measuredandchangesare sent once, at the top of each watch, andresult_detailholds 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 undernot_measuredwith the reason, never as flat. A read of the monitoring store; the investigation agent may call it. - Known patterns (Darling-only) —
get_known_patternslists 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. Everyget_alert_historyrow carriesknown_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 inconfig.config_known_patterns(V214) and are written through the owner-rights functionsconfig.insert_known_pattern,update_known_patternanddelete_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/ settingdescription/setting_type/ generated change-narrative enrichment is not collected here and is omitted. The Dashboard’sget_blocking_deadlock_statsaggregate is not hosted (Darling has no blocking/deadlock rollup table — useget_blocking/get_deadlocksfor the raw events). - Blocking / deadlocks —
-
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, spinlockdescription, plan-cachebloat_level, and CPU-schedulerpressure_level/recommendationare 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 storedsample_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 arenullrather than 0 when that interval was unknowable — a restart, not quiet.get_resource_semaphoreemits the Dashboard’ssample_interval_secondsagain now that the memory-grant collector stores it (V128),nullwithinterval_known: falseon a restart marker or a pre-V128 row;max_target_memory_mb, the workspace-memory ceiling, is added since the store carries it. - Latch / spinlock —
-
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 moreshared_buffersor 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, frompg_stat_database). Temp files are the reason it exists: they are workwork_memcould 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 carriespeak_numbackends, the window’s peak of connected backends for that database — a level, never differenced,nullon a pre-V133 history rather than 0 — deliberately not summed across databases (the peaks land at different instants); themax_connectionsfraction lives on thePG_CONNECTION_SATURATIONfact, 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) andget_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) andget_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: anidle in transactionsession 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 onpeak_horizon_age, where-1means the session pinned NOTHING, and tells you so rather than letting a long duration imply otherwise. Pairs withget_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.
- Waits and queries —
-
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_namerequired),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_namefor one database per file),get_query_trend(one query’s per-collection history byquery_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_trendreproduces Lite’s miss vocabulary (Page Life Expectancy is intentionally not collected; an unknown counter hands back the collected names).get_memory_trendcarries atotal_granted_mbfield for field-for-field parity with Lite, joined per point from the memory-grant series (the samev_memory_grant_statssum the viewer’s overlay charts plot) — a point no grants snapshot covers within 30 seconds stays an explicit null, with agranted_notenamingget_memory_grants, never a fabricated 0 (#3529, #3548). -
-
System-health parse-on-read tools — the Dashboard’s
get_health_parser_*family, over Darling’s rawsystem_health_events:-
get_health_parser_system_health(corruption + contention counters),get_health_parser_severe_errors(severity ≥ 19, withdatabase_idresolved 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 sharedSystemHealthParser(the same parser the viewer’s System Events tab uses) and gate with the service-side twin of the viewer’sSystemEventSignificance— returning the same SIGNIFICANT warning set the Dashboard surfaces (sp_HealthParser at@warnings_only = 1).get_health_parser_system_healthis the one UNGATED category (its counter series plots every snapshot). Each row carries the full sp_HealthParser column set keyed on the event’sevent_time; the tools window onevent_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/listserves 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 assystem_health_empty_windows. Unknown names are reported, not errors; called with no arguments it lists the tools that have guides and the topics. Theget_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 V131route— where the post went — fleet-wide by default, or scoped to a server;external_sourcenames 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 carriesexternal_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 itsseverities, 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 sharedDailyHealthBandCalculator, plus the signals behind it).
- Alerts —
-
Fleet sweep reports (Darling-only) —
get_sweep_reportsreads the scheduled Fleet Sweep Reports — the stateful whole-fleet summaries the service persists at the configured cadence (get_alert_settings‘fleet_sweepgroup; 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. Onesweep_id(as a STRING — the ids are too large for a JSON number to round-trip) fetches one sweep in full. The sameFleetSweepPresentationbuilders and store reads the web feed’s/api/sweepsroutes 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: falseon a sweep means DELIVERY WAS OFF while it ran, andinstruments_alive: falsemeans the sweep could not prove its own data sources — quiet is not clean, and theinstrument_livenessblock says which instrument went unproven. A stored read; no monitored server is touched. -
Daily Health Report (Darling-only, #7041) –
get_daily_health_reportbuilds the report for one day from the monitoring store and sends nothing, so an agent or a person can preview it. The optionaldateis 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. Withoutdateyou 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 earlierdatethey are today’s. The report’s own delivery row is left out of the alerts count.send_daily_health_report_nowis a write tool. It is served whenmcp.allowWritesis on, or to a namedoperatortoken, 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 theDaily Health Reportmetric of thereportsfamily, 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 whiledaily_report.enabledis 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 thedaily_reportgroup ofget_alert_settingsandupdate_alert_settings(enabled,send_atas"HH:mm",time_zonewherenullis the service host’s zone, andtitlewherenullisDaily 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/catalogvocabulary 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 optionalfolderargument lists one folder, and an empty string lists the top level; every personal view is listed, markedpersonal: 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 optionalfolder),update_custom_view(validate then replace in place, optimistic-concurrency onversion;folderomitted 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 answersrefused): 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
ValidateDefinitionauthority asvalidate_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. - Discover —
-
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 withundo: nullbecause an expired rule had no effect),set_mute_rule_enabled, and the route writescreate_notification_route/update_notification_route/set_notification_route_enabled/set_notification_route_fallback/delete_notification_route(update_notification_routealso sets a route’saction_approvalandapproval_single_person, and it can only tighten them: see Level 3 server actions: approval), andupdate_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; themcprole holds no read or write on a secret column and writes them through the store’sconfig.set_notification_channelsfunction, 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_routetakes the sameseveritiesword (defaultboth, so a route takes alerts of both severities unless you limit it, and any other value is refused asinvalid), 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_routechanges the match, scope, enabled flag, resolution override, severity filter (severities:critical,warningorboth), 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 labelledclient says(any client can send any name) and the names of the fields changed, never a value), plusdismiss_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_rulealso take an optional lower-caseexternal_sourcethat limits a rule to the alerts one external source raised; a name that is not a valid source name is refused, andupdate_mute_ruleclears it with an explicit null) — the SAME configget_alert_settings/get_mute_rulesread and the Viewer’s Settings window writes.update_alert_settingsis a PARTIAL update of the alert configuration: read viaget_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-bumpsconfig_versionso the running service hot-reloads within one collection sweep.create_mute_rule/update_mute_rule/delete_mute_rule/set_mute_rule_enabledreuse the SAMEPgMuteRuleStoreget_mute_rulesreads through (and the same GUID id-generation the Viewer’s mute-create path uses).set_mute_rule_enabledis the headless twin of the Viewer’s mute-rule checkbox: it writesenabledand nothing else, so a rule can leave force and return keeping its id, its reason and thecreated_at_utctheStale Mute Rulesself-alert ages it from — where a delete-and-re-create resets that clock and delivers the suppressed alerts in between.update_mute_ruleis the headless twin of the Viewer’s Edit dialog on the same terms: a PARTIAL update (send only the fields to change, in the shapeget_mute_rulesreturns; an explicit JSONnullclears a field, so a bounded rule can be made permanent again) written through the store’s own full-rowUpdateAsync— whose SET list does not namecreated_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_settingsspans the two singleton config rows the alert engine reads: every knob is onconfig_alert_settingsexcept the per-fingerprint DELIVERY cooldown, which is stored asconfig_notification.email_cooldown_minutesand reported and accepted asdelivery.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-levelcooldown_minutesgates whether the engine FIRES,delivery.cooldown_minutesbounds 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, anddelivery.modePerEventopts 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 isupdate_notification_channels, which sets the SMTP password, the webhook URLs and the keys sealed and never shows them back (themcprole 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 theconfig.set_notification_channelsfunction). It is part of what the MCP token gates — see What a token can reach below. -
Recurring mute rules (Darling-only, #7040):
create_mute_ruleandupdate_mute_ruletake an optional schedule.recur_daysis a list of day names (MonorMonday, any case) and is omitted for every day.recur_startandrecur_endareHH:mmand go together.recur_time_zoneis 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, sendrecur_startandrecur_endas null toupdate_mute_rule, and the days and zone clear with them.get_mute_rulesreturnsrecur_days,recur_start_time,recur_end_timeandrecur_time_zoneon each rule, plusschedule(one line of text),in_window_nowandnext_window_start_utc. A rule with no times is a one-off rule. -
Webhook signing key tools (Darling-only, #6394) —
generate_webhook_signing_keyandremove_webhook_signing_key, each with an optionalroute_id(none is the default destination’s key in Settings > Notifications, a number is that route’s own generic webhook).generate_webhook_signing_keymakes 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’sconfig.set_webhook_signing_keyfunction; themcprole 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 passesreplace_pending_rotation: true. A destination with no saved generic webhook URL, and aroute_idthat does not exist, are refused and write nothing.remove_webhook_signing_keyclears 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_routerefuses 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) andremove_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_Attentionand the oldPerformanceMonitor_LongQueryCompletions; once the server is removed,--drop-xe-sessions --print-sqlprints 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_serverchanges one saved server in place and is served under the samemcp.allowServerAdminsetting asadd_serversandremove_server; an edit that points Windows authentication at a connection whose server identity is not verified is refused asadd_serversrefuses it, before any connection is made.add_serverstakes a JSON array of server objects (hostrequired; optionaldisplay_name/database/read_only_intent/multi_subnet_failover;authWindows/SQLwithusername+passwordfor SQL; and the exposed TLS optionsencrypt_modeOptional/Mandatory/Strict+trust_server_certificate) and processes them in order: it validates each entry, PROBES the connection in-process (reusing the sameDarlingServerConnector.ProbeAsyncthe--test-connectionverb runs — the service holds the network path + credentials, so notest_connectcommand 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 isconnection_failedand the batch continues.authalso takes the two non-interactive Microsoft Entra modes (#3484). WithServicePrincipal,usernameis the app’s client id andpasswordis its client secret. The other mode isManagedIdentity. Only the interactive Entra modes (MFA, device code, default credential) areinvalid, because they need a signed-in user and cannot run headless. Off Windows, a literal SQL password or client secret is refused asinvalidtoo, because encryption at rest is Windows DPAPI. Give anenv:NAMEorfile:/run/secrets/<name>reference instead, the same two forms thatdarling.jsontakes for every secret. A server is refused ascollideswhen 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 ascollidesas well, because two identities can hash to one id. Nothing is written for acollidesentry. If saving an entry fails, that entry and every entry after it arenot_savedand are not probed. The entries before it stayadded.remove_serverDELETEs a monitored server by name (resolved the same way everyserver_nameis) — already-collected history is kept. Both write only the monitoring store’sconfig.config_monitored_serversregistry; neither runs anything on a monitored server beyond the one-time probe. The SQL password travels to the endpoint insideadd_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.