feat: Add dashboard table onClick to MCP schemas and prompts

[pulpdrew]

Summary

This PR updates the MCP schemas and prompts to include dashboard table custom on-click behaviors.

I also remove the IS_DASHBOARD_LINKING_ENABLED toggle, as this is the last change that is part of the dashboard linking MVP.

Screenshots or video

Given the prompt

Create a hyperdx services catalog dashboard which includes RED metrics. Create dashboards for each of my services, and link from the catalog to the individual dashboards.

Claude is able to one-shot a catalog which correctly links to per-service dashboards when clicking the RED metrics table rows:

How to test on Vercel preview

This can be tested locally with the MCP server.

References

• Linear Issue: Closes HDX-4067
• Related PRs:

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	May 15, 2026 5:44pm

[changeset-bot]

🦋 Changeset detected

Latest commit: e89800d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@hyperdx/api	Patch
@hyperdx/app	Patch
@hyperdx/otel-collector	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

🟡 Tier 3 — Standard

Introduces new logic, modifies core functionality, or touches areas with non-trivial risk.

Why this tier:

• Diff size: 767 production lines changed (Tier 2 max: < 250)
• Cross-layer change: touches frontend (packages/app) + backend (packages/api)

Review process: Full human review — logic, architecture, edge cases.
SLA: First-pass feedback within 1 business day.

Stats

• Production files changed: 9
• Production lines changed: 767 (+ 721 in test files, excluded from tier calculation)
• Branch: drew/mcp-onclick
• Author: pulpdrew

To override this classification, remove the review/tier-3 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

[github-actions]

PR Review

Solid PR — the MCP path now properly mirrors REST v2 validation for onClick link-outs and dashboard-level filters, the schemas are richly documented, and there are ~700 lines of round-trip tests covering both the happy and rejection paths. Feature-flag cleanup is mechanical and complete.

Must-fix

• ⚠️Prompt / schema claim a server validation that doesn't exist. Both prompts/dashboards/content.ts (lines 1036–1038) and tools/dashboards/schemas.ts (in mcpOnClickDashboardSchema.filters and mcpFiltersParam descriptions) tell the LLM that "the save tool validates this and will reject onClick filters whose expression is not declared on the target dashboard" with the exact error string "onClick filter expressions are not declared on the target dashboard and would be silently dropped at click time: ...". Grepping getInvalidOnClick* / getMissing* shows only two onClick validators (getMissingOnClickDashboards, getInvalidOnClickSearchSources) — neither in MCP nor REST does it check filter-expression-vs-target-declared-filters. The LLM will rely on a phantom rejection that never fires → soft-broken drilldowns ship without error. Fix: either implement the validation (REST + MCP, with a shared helper) or rewrite the prompt/schema text to describe it as a client-side check we want you to perform via hyperdx_get_dashboard before saving, rather than a server enforcement.

Nits (non-blocking)

• The four if (missingOnClickDashboards.length > 0) / if (invalidOnClickSearchSources.length > 0) blocks in saveDashboard.ts are identical in createDashboard and updateDashboard (and identical to the REST handler). Worth a small helper to keep error wording from drifting across the three call sites later.
• mcpOnClickSearchSchema.whereLanguage description says "Optional, but set it explicitly…" — the field is actually required at the schema layer (no .optional()), even though the underlying SearchConditionLanguageSchema is .optional(). The test "should accept onClick without whereLanguage" passes only because the inner schema accepts undefined. Either drop the "Optional, but…" wording or wrap with .optional() to match the test's intent.

[github-actions]

Deep Review

✅ No critical issues found.

🟡 P2 -- recommended

• packages/api/src/mcp/tools/dashboards/schemas.ts:281-283 -- the onClick.filters description tells the LLM "The save tool validates this and will reject onClick filters whose expression is not declared on the target dashboard," but saveDashboard.ts only wires getMissingOnClickDashboards and getInvalidOnClickSearchSources; no cross-check against the target dashboard's declared filters[].expression exists in this diff or in the v2 REST router.
  • Fix: Either implement an getInvalidOnClickDashboardFilterExpressions helper that loads target dashboards and compares declared filters[].expression against each tile's onClick.filters[].expression, or strike the "will reject" promise and keep only the "silently dropped at click time" guidance.
  • _{ce-correctness-reviewer, ce-api-contract-reviewer, ce-testing-reviewer, ce-maintainability-reviewer}
• packages/api/src/mcp/prompts/dashboards/content.ts:1034-1038 -- this prompt section quotes a rejection error message ("onClick filter expressions are not declared on the target dashboard and would be silently dropped at click time: ...") that is never emitted, while a separate section at lines 229-231 and 1209-1214 correctly says the filter is silently dropped — the LLM gets two contradictory contracts in the same prompt.
  • Fix: Delete the quoted "save is rejected" block so the silent-drop guidance is the single source of truth.
  • _{ce-correctness-reviewer, ce-api-contract-reviewer, ce-maintainability-reviewer}
• packages/api/src/mcp/tools/dashboards/saveDashboard.ts:445-455 -- the update path's new invalidOnClickSearchSources rejection branch has no test; the only update-path onClick test (dashboards.test.ts:1597-1642) exercises the missing-dashboard branch but not the invalid-search-source branch, so a future change that drops the gate on PUT while keeping it on POST would not regress any test.
  • Fix: Add an update-path test that round-trips a tile to a dashboard, then updates with onClick.target.id pointing at a metric/session source and asserts the rejection text.
  • _{ce-testing-reviewer}
• packages/app/src/components/DBTableChart.tsx:226-235 -- after removing IS_DASHBOARD_LINKING_ENABLED, getOnClickLink now wins unconditionally over getRowSearchLink, but packages/app/src/components/__tests__/DBTableChart.test.tsx has no assertions on onClick/onRowClick behavior — the behavior change ships untested.
  • Fix: Add a test that renders DBTableChart with both getOnClickLink and getRowSearchLink and asserts the configured onClick URL wins.
  • _{ce-testing-reviewer}
• packages/api/src/mcp/__tests__/dashboards.test.ts:1645-1826 -- the new top-level filters param tests cover happy-path round trips and id preservation but never assert that a filter with a bogus sourceId is rejected by getMissingSources (which now scans both tiles and filters in routers/external-api/v2/utils/dashboards.ts:777-811).
  • Fix: Add a test that calls hyperdx_save_dashboard with a top-level filter whose sourceId is a non-existent ObjectId and asserts isError plus the "Could not find source IDs" message.
  • _{ce-testing-reviewer}

🔵 P3 nitpicks (8)

• packages/api/src/mcp/tools/dashboards/schemas.ts:635-648 -- mcpDashboardFilterSchema accepts an optional id even on the create path, but the downstream createDashboardBodySchema -> externalDashboardFilterSchema = externalDashboardFilterSchemaWithId.omit({ id: true }) retains its parent's .strict(), so a create call that supplies id surfaces as Unrecognized key(s) in object: 'id' rather than being silently stripped.
  • Fix: Either branch the MCP schema on presence of dashboard id (forbid filter id on create) or change the description from "may be omitted on CREATE" to "must be omitted on CREATE; server will generate one."
  • _{ce-correctness-reviewer, ce-api-contract-reviewer}
• packages/api/src/routers/external-api/v2/utils/dashboards.ts:943-946 -- getMissingOnClickDashboards passes raw user-supplied strings into Dashboard.find({ team, _id: { $in: [...] } }); a non-ObjectId target.id triggers a Mongoose CastError that escapes the friendly "Could not find the following onClick dashboard IDs: …" message path.
  • Fix: Filter dashboardIds (and the parallel source-id set in getInvalidOnClickSearchSources) through mongoose.Types.ObjectId.isValid first and surface the rejects in the same "missing" list.
• packages/api/src/mcp/tools/dashboards/saveDashboard.ts:171-176 -- Promise.all runs fetchSourcesForValidation(teamId) in parallel with getInvalidOnClickSearchSources(teamId, tilesWithId), but the latter internally calls getSources(team.toString()); the hoist comment claims a single round-trip but the source list is fetched twice per save.
  • Fix: Add a getInvalidOnClickSearchSources overload that accepts a pre-fetched sources array and reuse the hoisted sources.
• packages/api/src/mcp/tools/dashboards/schemas.ts:215-225 -- whereTemplate is z.string().max(10000).optional() with no .min(1), while the sibling mcpOnClickFilterTemplateSchema.template is .min(1).max(10000); an empty string is accepted but is a no-op at render time.
  • Fix: Add .min(1) to both mcpOnClickSearchSchema.whereTemplate and mcpOnClickDashboardSchema.whereTemplate (and the matching common-utilsOnClickSchema shapes) to make "omit it" the only way to express "no template."
• packages/api/src/mcp/__tests__/dashboards.test.ts:1988-2075 -- the prompt-content tests assert on exact substrings such as 'type: "search"', 'mode: "id"', and the error fragments 'onClick search source IDs' / 'onClick dashboard IDs'; routine docs polish will break the suite without flagging real behavior change.
  • Fix: Replace prose substrings with stable section markers (e.g. == TABLE TILE LINKING) and extract the two error-message templates to a shared const consumed by both saveDashboard.ts and the prompt builder.
  • _{ce-testing-reviewer, ce-maintainability-reviewer}
• packages/api/src/mcp/tools/dashboards/saveDashboard.ts:223-244 -- the two-block missingOnClickDashboards / invalidOnClickSearchSources gate is duplicated verbatim in updateDashboard:434-455, mirroring the existing parallel between the create and update paths for missing sources/connections/heatmaps.
  • Fix: When the next shared gate lands, extract runSharedTileValidations(teamId, tilesWithId, sources) returning { isError, content } | null so future rules touch one site.
• packages/api/src/mcp/__tests__/dashboards.test.ts:1340-1430 -- whereTemplate round-trip is asserted only on the dashboard-typed onClick test; the search-typed onClick tests never set or verify whereTemplate.
  • Fix: Add whereTemplate to one of the existing search onClick tests and assert it survives the round trip.
• packages/app/src/components/DBTableChart.tsx:226-235 -- removing NEXT_PUBLIC_IS_DASHBOARD_LINKING_ENABLED activates onClick row-click navigation in every deployment that has an onClick configured, without a changelog note about the operator-visible behavior shift.
  • Fix: Expand .changeset/strange-tigers-relate.md to call out that the NEXT_PUBLIC_IS_DASHBOARD_LINKING_ENABLED env var is removed and onClick navigation is now always-on.

---

Reviewers (4): ce-correctness-reviewer, ce-testing-reviewer, ce-api-contract-reviewer, ce-maintainability-reviewer.

Testing gaps:

• No test for the schema's documented (but unimplemented) "reject undeclared onClick filter expression" gate — implement or strike the claim.
• Update-path invalidOnClickSearchSources branch has no regression test.
• Frontend DBTableChart row-click behavior after flag removal has no test.
• Top-level dashboard filters with missing sourceId is uncovered.
• whereTemplate is round-tripped only on dashboard-typed onClick tests, not search-typed.

[github-actions]

E2E Test Results

✅ All tests passed • 178 passed • 3 skipped • 1213s

Status	Count
✅ Passed	178
❌ Failed	0
⚠️ Flaky	3
⏭️ Skipped	3

Tests ran across 4 shards in parallel.

View full report →

[brandon-pereira]

This mostly worked - I got an alert chip (forgot to screenshot) when I first tried it, but after prompting the above it seems to be fixed. Not sure if thats a gap in our docs - or something else.

[knudtty]

LGTM - great!

[pulpdrew]

This mostly worked - I got an alert chip (forgot to screenshot) when I first tried it, but after prompting the above it seems to be fixed. Not sure if thats a gap in our docs - or something else.

Nice find. The primary issue appears that the existing MCP dashboard schemas were missing filters entirely, so the target dashboard could not be created with filters. I have fixed that, and also added updated prompts/examples to keep the agent from generating filters in links to dashboards without the corresponding filter

@brandon-pereira

[brandon-pereira]

LGTM - this is awesome 🥳

[github-actions]

PR Review

• ⚠️Prompt/schema claim a server validation that doesn't exist → packages/api/src/mcp/prompts/dashboards/content.ts:1034-1038 says the save is rejected when an onClick.filters[i].expression isn't declared on the target dashboard, and packages/api/src/mcp/tools/dashboards/schemas.ts:~1583 ("The save tool validates this and will reject onClick filters whose expression is not declared on the target dashboard.") repeats the claim. But saveDashboard.ts only runs getMissingOnClickDashboards and getInvalidOnClickSearchSources — there is no check that filter expressions match declared DashboardFilter expressions on the target. Elsewhere in this same PR the docs correctly state the value is silently dropped at click time. Pick one and apply it consistently: either reword these two spots to "silently dropped at click time" (matches reality), or add the rejection in routers/external-api/v2/utils/dashboards.ts (and a corresponding error branch in the MCP + REST save paths and an integration test). As-is, the LLM may skip the safer whereTemplate fallback because it believes the save will fail loudly.

Otherwise:

• Server-side validation in mcp/tools/dashboards/saveDashboard.ts correctly mirrors the REST POST/PUT paths (same error strings, same ordering) so MCP and REST stay in lockstep.
• Test coverage is thorough (round-trip, ID/template targets, search vs dashboard, raw-SQL tile, missing-dashboard rejection, non-log/trace rejection, update-path validation, prompt-content lock-down).
• IS_DASHBOARD_LINKING_ENABLED removal is clean — feature flag dropped from .env.development, run-e2e.js, config.ts, and both consumers (OnClickFormButton.tsx, DBTableChart.tsx).
• Changeset is present and correctly scoped to @hyperdx/api.