feat(mcp): expose connectionId for Postgres/DuckDB direct queries

[georgemunyoro]

Problem

Postgres and DuckDB direct-query data warehouse connections are fully supported on the backend (HogQLQuery, HogQLMetadata, and DatabaseSchemaQuery all accept connectionId), but the MCP-side zod schemas didn't include the field. zod strips unknown keys by default, so any agent attempt to target a direct source got silently downgraded to ClickHouse — making the entire direct-query feature invisible from MCP clients.

Changes

Pass connectionId through the three HogQL-shaped MCP tools:

• query-run — added connectionId to HogQLQuerySchema. Flows through automatically since the schema is part of QueryRunInputSchema's discriminated union.
• query-validate — added connectionId to QueryValidateInputSchema and forwarded through the typed validate() client method.
• hogql-schema — added connectionId to HogQLSchemaInputSchema and forwarded into the DatabaseSchemaQuery body.

Tool descriptions now point agents at external-data-sources-list to discover available connection ids.

sendRawQuery (native-SQL passthrough on HogQLQuery) was considered but deliberately deferred: the backend HogQLMetadata schema is extra="forbid" with no equivalent field, so exposing sendRawQuery on query-run without a matching path on query-validate would break the validate-first pattern this work is built around. Add to both at once when the backend metadata path supports raw-query validation.

How did you test this code?

Automated tests only — I'm an agent, no manual MCP Inspector / Claude Desktop runs.

• pnpm --filter=@posthog/mcp typecheck is clean.
• No backend changes; no Python tests required.

Publish to changelog?

Yes.

🤖 LLM context

Co-authored with Claude Code in the same session as #56185. The bug was discovered while listing follow-up MCP work — the backend already accepted connectionId end-to-end, but no MCP tool exposed it.

[greptile-apps]

Prompt To Fix All With AI

This is a comment left during a code review.
Path: services/mcp/src/schema/tool-inputs.ts
Line: 368-387

Comment:
**`sendRawQuery` not forwarded to validate**

`query-run` now accepts `sendRawQuery: true` (on `HogQLQuerySchema`) to pass native SQL straight through to the external source without HogQL translation. `query-validate`, however, has no equivalent flag, so an agent writing native Postgres/DuckDB SQL cannot validate it before executing — it would be parsed as HogQL and likely return misleading errors.

If the backend `HogQLMetadata` endpoint supports `sendRawQuery`, adding the field to `QueryValidateInputSchema` and forwarding it in `client.ts`'s `validate()` would close that workflow gap.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "feat(mcp): pass connectionId to query-ru..." | Re-trigger Greptile}

[Copilot]

Pull request overview

This PR exposes connectionId in the MCP-side Zod schemas (and forwards it through handlers) so MCP clients can target Postgres/DuckDB direct-query external data sources instead of being silently downgraded to ClickHouse.

Changes:

• Added optional connectionId to the HogQL-shaped MCP input schemas (HogQLQuery, query-validate, hogql-schema).
• Forwarded connectionId through the MCP handlers into the API client request bodies for validate/schema flows.
• Updated tool descriptions and regenerated JSON schema artifacts/snapshots to reflect the new field.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
services/mcp/src/schema/query.ts	Adds connectionId to HogQLQuerySchema.
services/mcp/src/schema/tool-inputs.ts	Adds connectionId to HogQLSchemaInputSchema and QueryValidateInputSchema.
services/mcp/src/tools/query/validate.ts	Plumbs connectionId from tool params into api.insights().validate(...).
services/mcp/src/tools/query/schema.ts	Adds params typing and forwards connectionId into DatabaseSchemaQuery request body.
services/mcp/src/api/client.ts	Adds optional connectionId to validate() and conditionally includes it in the HogQLMetadata body.
services/mcp/schema/tool-inputs.json	Regenerated schema JSON to include connectionId in relevant inputs.
services/mcp/schema/tool-definitions.json	Updates tool descriptions to document connectionId usage and discovery.
services/mcp/schema/tool-definitions-all.json	Same description updates in the “all” bundle.
services/mcp/tests/unit/snapshots/tool-schemas/v1/query-run.json	Snapshot updated to include connectionId in the HogQLQuery shape(s).
services/mcp/tests/unit/snapshots/tool-schemas/v1/query-validate.json	Snapshot updated to include connectionId.
services/mcp/tests/unit/snapshots/tool-schemas/v1/hogql-schema.json	Snapshot updated to include connectionId.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[deployment-status-posthog]

Deploy status

Environment	Status	Deployed At	Workflow
dev	✅ Deployed	2026-04-29 21:35 UTC	Run
prod-us	✅ Deployed	2026-04-29 21:49 UTC	Run
prod-eu	✅ Deployed	2026-04-29 21:53 UTC	Run