Skip to content

MCP docs: lead with what agents cannot do, retire the blast-radius framing - #1983

Merged
erikdarlingdata merged 1 commit into
devfrom
fix/mcp-readme-tone
Aug 1, 2026
Merged

MCP docs: lead with what agents cannot do, retire the blast-radius framing#1983
erikdarlingdata merged 1 commit into
devfrom
fix/mcp-readme-tone

Conversation

@erikdarlingdata

@erikdarlingdata erikdarlingdata commented Aug 1, 2026

Copy link
Copy Markdown
Owner

Erik's call: the networked-MCP language made it sound like AI agents can read and write to SQL Server at will. The code never allowed that, and the docs now say so first.

What changed (tone and structure only - zero facts removed)

  • The 'Blast radius, stated honestly' paragraph is now 'What a token-holder can - and cannot - do', and it opens with the boundary: no MCP tool runs SQL an AI client wrote against your monitored servers; no such tool exists, and a stored custom view structurally cannot become one (composed queries name only collect.* tables). The only live-server contact - analyze_server's plan fetch and add_servers' one-time probe - runs the product's own fixed read-only queries under the least-privilege monitoring login, which has no write grants to hit. THEN the full honest capability list, the mcp-role bounds, and the secret-column carve, all verbatim from before.
  • The web endpoint's 'Blast radius' paragraph is now 'What a web token can reach' - same facts, boundary-first phrasing.
  • The three tool-bullet tails ('this widens what an MCP token can do') now say the surface 'is part of what the MCP token gates', with the cross-reference link text renamed to match.
  • The add_servers credential paragraph keeps every wire fact (plaintext HTTP, DPAPI at rest, TLS-proxy guidance, prefer integrated auth) minus the dramatics.
  • The root README's MCP section gains a two-sentence boundary statement so the first page a prospect reads answers the fear directly.

Ground truth verified before rewriting

  • Lite/Mcp/*: zero live SqlConnection/ExecuteReader sites; analyze_server's own tool description states remediation T-SQL is 'advisory only and never executed'.
  • Darling: the two live-contact paths (plan fetch, onboarding probe) confirmed as fixed product queries under the monitoring login; all write tools land in config.* store tables under the mcp role.
  • No test pins any of the edited prose (the one 'blast radius' in a test file is an internal doc comment, untouched).

Docs-only diff: expect the path-filter short-circuit on checks.

🤖 Generated with Claude Code

@erikdarlingdata @claude
MCP docs lead with the boundary, not the warning
2f9e0e2 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@erikdarlingdata
erikdarlingdata merged commit ae278b7 into dev Aug 1, 2026
4 checks passed
@erikdarlingdata
erikdarlingdata deleted the fix/mcp-readme-tone branch August 1, 2026 10:33
erikdarlingdata added a commit that referenced this pull request Aug 1, 2026
@erikdarlingdata @claude
Merge origin/dev into the PVS lane, renumbering the migration to V47
35d65f6 
Dev moved four PRs ahead of this branch's base. #1987 (plan_correction)
took Darling migration V46, Lite DuckDB schema v50, and CI worker sizing
42/53; #1983 moved both READMEs; #1949 reordered the query grids.

Every conflict is resolved keep-both -- the two collectors are unrelated
and both belong in the catalog, both schedule-defaults tables, both
golden schemas, and both viewer probe ladders.

The migration is renumbered 45 -> 47, which is not cosmetic. The applier
reads MAX(version) from darling_schema_version and skips anything at or
below it, so a store already stamped 46 by #1987 would have skipped a
late-arriving 45 forever: upgraded stores would silently lack pvs_stats
while fresh stores got it from V1's generated schema. 45 is now
permanently unused and the comments at every site say so.

Worker sizing re-derived from the product's own formula now that both
collectors are in the catalog: HypertableCount = 40 collectors +
collection_log = 41, so background workers = 43 and worker processes =
54, in build.yml and nightly.yml.

Lite DuckDB CurrentSchemaVersion 50 -> 51 with a log-only migration arm,
matching how every new-table collector since v37 has been registered
(the table itself comes from GetAllTableStatements and the v_pvs_stats
view from ArchivableTables, both catalog-derived).

Count assertions that both lanes had independently bumped 38 -> 39 now
read 40, and the ViewerGridPayloadColumnOrderPinTests twin count is 18.
Two dev tests needed real fixes rather than renumbering:
DarlingPlanCorrectionLiveMigrationTests rewound only V46's stamp row,
which becomes a no-op once 47 sits above it, so it now clears every
stamp above 44 and expects both scripts; and the probe ladder gained a
V47 rung ahead of V46.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
erikdarlingdata added a commit that referenced this pull request Aug 1, 2026
@erikdarlingdata @claude
Docs: give plan_correction the two rows it was missing (#1951)
4b09329 
Noticed while checking that my own README rows landed in the right files
after #1983 moved them. #1987 shipped plan_correction without adding it
to the root README's collector table or the Darling README's migration
table, so both tables documented one of the two collectors added this
week and the migration table jumped V30 -> V47 with V46 unexplained.

Both are one-line, same-format additions next to rows this PR already
touches. Nothing about #1952's behavior changes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@erikdarlingdata