:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(canvas): run canvas mcp tools from the desktop host (#123289)
Harley Alexander1638a4b752dc
diff --git a/products/canvas/backend/sandbox/sandbox_document.html b/products/canvas/backend/sandbox/sandbox_document.htmlindex 25347221b42d..1dd9fe8315f0 100644--- a/products/canvas/backend/sandbox/sandbox_document.html+++ b/products/canvas/backend/sandbox/sandbox_document.html@@ -180,6 +180,14 @@actions: {invoke: (verb, payload) => call("actionInvoke", { verb, payload: payload ?? {} }),},+ // Run a PostHog MCP tool as the viewer. Every tool must be declared in+ // capabilities.posthog.tools. `read` takes read-only tools and may run on+ // load; `call` changes data, so wire it to a click (the host confirms):+ // `ph.tools.call("feature-flag-enable", { id })`.+ tools: {+ read: (tool, args) => call("toolRead", { tool, arguments: args ?? {} }),+ call: (tool, args) => call("toolCall", { tool, arguments: args ?? {} }),+ },// Read live third-party data with the viewer's own connection. Every// provider and tool must be declared in capabilities.connectors; the// result is cached per canvas for `refresh` seconds (default 60):diff --git a/products/desktop/packages/core/src/canvas/canvasCapabilities.ts b/products/desktop/packages/core/src/canvas/canvasCapabilities.tsindex 5344bce288af..644fb04a2a4b 100644--- a/products/desktop/packages/core/src/canvas/canvasCapabilities.ts+++ b/products/desktop/packages/core/src/canvas/canvasCapabilities.ts@@ -58,6 +58,14 @@ export function assertCanvasCapability(}return;}+ case "toolRead":+ case "toolCall": {+ const tool = (payload as { tool?: string })?.tool;+ if (!tool || !(capabilities.posthog.tools ?? []).includes(tool)) {+ throw new Error(`Tool "${tool ?? ""}" is not allowed by this canvas`);+ }+ return;+ }case "agentRequest":if (!capabilities.posthog.agentRequests) {throw new Error("Agent requests are not allowed by this canvas");diff --git a/products/desktop/packages/core/src/canvas/dashboardSchemas.ts b/products/desktop/packages/core/src/canvas/dashboardSchemas.tsindex 4245ff439ca5..1d71d925032d 100644--- a/products/desktop/packages/core/src/canvas/dashboardSchemas.ts+++ b/products/desktop/packages/core/src/canvas/dashboardSchemas.ts@@ -266,6 +266,27 @@ export const canvasActionResultSchema = z.object({});export type CanvasActionResult = z.infer<typeof canvasActionResultSchema>;+// One PostHog MCP tool a canvas may run, as the host renders it before running it.+export const canvasToolDefinitionSchema = z.object({+ name: z.string(),+ summary: z.string(),+ read_only: z.boolean(),+ destructive: z.boolean(),+});+export type CanvasToolDefinition = z.infer<typeof canvasToolDefinitionSchema>;++export const canvasToolInvokeInput = z.object({+ id: z.string().min(1),+ tool: z.string().min(1).max(200),+ arguments: z.record(z.string(), z.unknown()).default({}),+});++export const canvasToolResultSchema = z.object({+ tool: z.string(),+ result: z.record(z.string(), z.unknown()),+});+export type CanvasToolResult = z.infer<typeof canvasToolResultSchema>;+export const requestCanvasAgentInput = canvasAgentRequestInputSchema.extend({id: z.string().min(1),});diff --git a/products/desktop/packages/core/src/canvas/dashboardsService.ts b/products/desktop/packages/core/src/canvas/dashboardsService.tsindex e88a571abc06..0aedc9b2c5e7 100644--- a/products/desktop/packages/core/src/canvas/dashboardsService.ts+++ b/products/desktop/packages/core/src/canvas/dashboardsService.ts@@ -16,6 +16,8 @@ import {type CanvasSourceProject,type CanvasStateEntry,type CanvasStateScope,+ type CanvasToolDefinition,+ type CanvasToolResult,type CanvasVersion,type CanvasView,canvasSourceProjectSchema,@@ -40,6 +42,10 @@ import {ProjectApiError,} from "./projectApiClient";+// Outlasts the backend's MCP call timeout, so a stalled write still reaches the+// viewer as the backend's "the change can still apply" answer.+const CANVAS_TOOL_TIMEOUT_MS = 60_000;+// A canvas as the PostHog canvases API returns it.interface ApiCanvas {id: string;@@ -542,6 +548,44 @@ export class DashboardsService {return { verb: body.verb ?? input.verb, result: body.result ?? {} };}+ // The PostHog MCP tools a canvas may declare, from the action registry.+ async listTools(): Promise<CanvasToolDefinition[]> {+ const body = await this.api.json<{ tools?: CanvasToolDefinition[] }>(+ `canvases/actions/`,+ "list canvas tools",+ );+ return body.tools ?? [];+ }++ // Run one declared PostHog MCP tool as the viewer.+ async invokeTool(input: {+ id: string;+ tool: string;+ arguments: Record<string, unknown>;+ }): Promise<CanvasToolResult> {+ const res = await this.api.fetch(+ `canvases/${encodeURIComponent(input.id)}/tools/invoke/`,+ {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({ tool: input.tool, arguments: input.arguments }),+ signal: AbortSignal.timeout(CANVAS_TOOL_TIMEOUT_MS),+ },+ );+ const body = (await res.json().catch(() => ({}))) as {+ detail?: string;+ tool?: string;+ result?: Record<string, unknown>;+ };+ if (!res.ok) {+ throw new ProjectApiError(+ body.detail ?? `Failed to run canvas tool (${res.status})`,+ res.status,+ );+ }+ return { tool: body.tool ?? input.tool, result: body.result ?? {} };+ }+// Call one declared connector tool as the viewer.async callConnector(input: {approval_token?: string;diff --git a/products/desktop/packages/core/src/canvas/freeformSchemas.ts b/products/desktop/packages/core/src/canvas/freeformSchemas.tsindex 51c6896450b5..ecd2d518118d 100644--- a/products/desktop/packages/core/src/canvas/freeformSchemas.ts+++ b/products/desktop/packages/core/src/canvas/freeformSchemas.ts@@ -343,6 +343,8 @@ export const canvasToHostMessageSchema = z.discriminatedUnion("type", ["stateSet","stateList","actionInvoke",+ "toolRead",+ "toolCall","agentRequest","connectorCall",]),diff --git a/products/desktop/packages/core/src/canvas/invokeCanvasAction.test.ts b/products/desktop/packages/core/src/canvas/invokeCanvasAction.test.tsindex 772f02f63aa2..09fdddd265a4 100644--- a/products/desktop/packages/core/src/canvas/invokeCanvasAction.test.ts+++ b/products/desktop/packages/core/src/canvas/invokeCanvasAction.test.ts@@ -1,5 +1,5 @@import { describe, expect, it, vi } from "vitest";-import { invokeCanvasAction } from "./invokeCanvasAction";+import { invokeCanvasAction, invokeCanvasTool } from "./invokeCanvasAction";const input = {id: "canvas-1",@@ -60,4 +60,55 @@ describe("invokeCanvasAction", () => {expect(confirm).not.toHaveBeenCalled();expect(invoke).toHaveBeenCalledWith(input);});++ describe("invokeCanvasTool", () => {+ const writeTool = {+ name: "feature-flag-enable",+ summary: "Enable feature flag",+ read_only: false,+ destructive: false,+ };+ const readTool = {+ ...writeTool,+ name: "feature-flag-get-definition",+ read_only: true,+ };++ it.each([+ // A canvas must not change data from a load or render.+ [writeTool, false, true, "changes data"],+ [writeTool, true, false, "Canvas tool call canceled"],+ [writeTool, true, true, null],+ [readTool, false, false, null],+ ])(+ "runs %o from a gesture %s with approval %s",+ async (tool, fromGesture, allowed, error) => {+ const confirm = vi.fn().mockReturnValue(allowed);+ const invoke = vi+ .fn()+ .mockResolvedValue({ tool: tool.name, result: {} });+ const call = { id: "canvas-1", tool: tool.name, arguments: { id: 7 } };+ const result = invokeCanvasTool(+ call,+ fromGesture,+ async () => [writeTool, readTool],+ confirm,+ invoke,+ );+ if (error) {+ await expect(result).rejects.toThrow(error);+ expect(invoke).not.toHaveBeenCalled();+ } else {+ await expect(result).resolves.toEqual({+ tool: tool.name,+ result: {},+ });+ expect(invoke).toHaveBeenCalledWith(call);+ }+ if (confirm.mock.calls.length > 0) {+ expect(confirm).toHaveBeenCalledWith(tool, call.arguments);+ }+ },+ );+ });});diff --git a/products/desktop/packages/core/src/canvas/invokeCanvasAction.ts b/products/desktop/packages/core/src/canvas/invokeCanvasAction.tsindex b66bfa60f9bd..13d8ca17145e 100644--- a/products/desktop/packages/core/src/canvas/invokeCanvasAction.ts+++ b/products/desktop/packages/core/src/canvas/invokeCanvasAction.ts@@ -2,8 +2,12 @@ import type { z } from "zod";import {type CanvasActionDefinition,type CanvasActionResult,+ type CanvasToolDefinition,+ type CanvasToolResult,canvasActionDefinitionSchema,type canvasActionInvokeInput,+ canvasToolDefinitionSchema,+ type canvasToolInvokeInput,} from "./dashboardSchemas";export async function invokeCanvasAction(@@ -24,3 +28,32 @@ export async function invokeCanvasAction(}return invoke(input);}++// ph.tools.read runs without a click, so it takes read-only tools only.+// ph.tools.call comes from a click, and the viewer confirms every tool that+// is not read-only, with the exact arguments the canvas passes.+export async function invokeCanvasTool(+ input: z.infer<typeof canvasToolInvokeInput>,+ fromGesture: boolean,+ listTools: () => Promise<CanvasToolDefinition[]>,+ confirm: (+ tool: CanvasToolDefinition,+ args: Record<string, unknown>,+ ) => boolean,+ invoke: (+ input: z.infer<typeof canvasToolInvokeInput>,+ ) => Promise<CanvasToolResult>,+): Promise<CanvasToolResult> {+ const tools = canvasToolDefinitionSchema.array().parse(await listTools());+ const tool = tools.find((entry) => entry.name === input.tool);+ if (!tool) throw new Error(`Canvases cannot run the tool "${input.tool}"`);+ if (!fromGesture && !tool.read_only) {+ throw new Error(+ `"${input.tool}" changes data. Run it with ph.tools.call from a click.`,+ );+ }+ if (!tool.read_only && !confirm(tool, input.arguments)) {+ throw new Error("Canvas tool call canceled");+ }+ return invoke(input);+}diff --git a/products/desktop/packages/core/src/canvas/services.ts b/products/desktop/packages/core/src/canvas/services.tsindex 8fdadbcc1250..f420851726e1 100644--- a/products/desktop/packages/core/src/canvas/services.ts+++ b/products/desktop/packages/core/src/canvas/services.ts@@ -13,6 +13,8 @@ import type {CanvasSource,CanvasStateEntry,CanvasStateScope,+ CanvasToolDefinition,+ CanvasToolResult,CanvasVersion,CanvasView,DashboardRecord,@@ -113,6 +115,14 @@ export interface IDashboardsService {verb: string;payload: Record<string, unknown>;}): Promise<CanvasActionResult>;+ // The PostHog MCP tools a canvas may declare.+ listTools(): Promise<CanvasToolDefinition[]>;+ // Run one declared PostHog MCP tool as the viewer.+ invokeTool(input: {+ id: string;+ tool: string;+ arguments: Record<string, unknown>;+ }): Promise<CanvasToolResult>;// Call one declared connector tool with the viewer's own connection.callConnector(input: {id: string;diff --git a/products/desktop/packages/host-router/src/routers/dashboards.router.ts b/products/desktop/packages/host-router/src/routers/dashboards.router.tsindex b0910045caba..142ff4ea66b0 100644--- a/products/desktop/packages/host-router/src/routers/dashboards.router.ts+++ b/products/desktop/packages/host-router/src/routers/dashboards.router.ts@@ -17,6 +17,9 @@ import {canvasStateEntrySchema,canvasStateListInput,canvasStateSetInput,+ canvasToolDefinitionSchema,+ canvasToolInvokeInput,+ canvasToolResultSchema,canvasVersionSchema,canvasViewSchema,createDashboardInput,@@ -246,6 +249,19 @@ export const dashboardsRouter = router({.get<IDashboardsService>(DASHBOARDS_SERVICE).invokeAction(input),),+ listTools: publicProcedure+ .output(z.array(canvasToolDefinitionSchema))+ .query(({ ctx }) =>+ ctx.container.get<IDashboardsService>(DASHBOARDS_SERVICE).listTools(),+ ),+ invokeTool: publicProcedure+ .input(canvasToolInvokeInput)+ .output(canvasToolResultSchema)+ .mutation(({ ctx, input }) =>+ ctx.container+ .get<IDashboardsService>(DASHBOARDS_SERVICE)+ .invokeTool(input),+ ),callConnector: publicProcedure.input(canvasConnectorCallServiceInput).output(canvasConnectorCallResultSchema)diff --git a/products/desktop/packages/shared/src/canvas-contracts.ts b/products/desktop/packages/shared/src/canvas-contracts.tsindex 79dd46c78650..459ebad5b363 100644--- a/products/desktop/packages/shared/src/canvas-contracts.ts+++ b/products/desktop/packages/shared/src/canvas-contracts.ts@@ -26,6 +26,7 @@ export const canvasCapabilitiesSchema = z.object({.max(2).default([]),actions: z.array(z.string().min(1).max(64)).max(32).default([]),+ tools: z.array(z.string().min(1).max(200)).max(32).default([]),agentRequests: z.boolean().default(false),}).default({@@ -34,6 +35,7 @@ export const canvasCapabilitiesSchema = z.object({captureEvents: [],state: [],actions: [],+ tools: [],agentRequests: false,}),network: zdiff --git a/products/desktop/packages/ui/src/features/canvas/freeform/BuiltCanvas.test.tsx b/products/desktop/packages/ui/src/features/canvas/freeform/BuiltCanvas.test.tsxindex 94c6dd255cd3..6a891175ce54 100644--- a/products/desktop/packages/ui/src/features/canvas/freeform/BuiltCanvas.test.tsx+++ b/products/desktop/packages/ui/src/features/canvas/freeform/BuiltCanvas.test.tsx@@ -20,6 +20,7 @@ describe("BuiltCanvas", () => {captureEvents: [],state: [],actions: [],+ tools: [],agentRequests: false,},network: { origins: [] },diff --git a/products/desktop/packages/ui/src/features/canvas/freeform/canvasHostMessageRouter.ts b/products/desktop/packages/ui/src/features/canvas/freeform/canvasHostMessageRouter.tsindex af26f3f2009e..b4371580a26c 100644--- a/products/desktop/packages/ui/src/features/canvas/freeform/canvasHostMessageRouter.ts+++ b/products/desktop/packages/ui/src/features/canvas/freeform/canvasHostMessageRouter.ts@@ -221,6 +221,7 @@ export function createCanvasHostMessageRouter(// firing writes just by being loaded or rendered.if ((message.method === "actionInvoke" ||+ message.method === "toolCall" ||message.method === "agentRequest") &&!options.hasUserActivation()) {@@ -272,6 +273,7 @@ export function createCanvasHostMessageRouter(const result =message.method === "agentRequest" ||message.method === "actionInvoke" ||+ message.method === "toolCall" ||message.method === "connectorCall"? await call: await withRequestTimeout(call);diff --git a/products/desktop/packages/ui/src/features/canvas/freeform/freeformDataBridge.test.ts b/products/desktop/packages/ui/src/features/canvas/freeform/freeformDataBridge.test.tsindex 5cbafa28c645..a71ba7394aee 100644--- a/products/desktop/packages/ui/src/features/canvas/freeform/freeformDataBridge.test.ts+++ b/products/desktop/packages/ui/src/features/canvas/freeform/freeformDataBridge.test.ts@@ -29,6 +29,7 @@ const capabilities: CanvasCapabilities = {captureEvents: ["allowed-event"],state: ["user"],actions: ["tasks.create"],+ tools: [],},network: { origins: [] },connectors: [{ provider: "github", tools: ["list_pull_requests"] }],diff --git a/products/desktop/packages/ui/src/features/canvas/freeform/freeformDataBridge.ts b/products/desktop/packages/ui/src/features/canvas/freeform/freeformDataBridge.tsindex 7243092eae2b..edc9fcc7bfb9 100644--- a/products/desktop/packages/ui/src/features/canvas/freeform/freeformDataBridge.ts+++ b/products/desktop/packages/ui/src/features/canvas/freeform/freeformDataBridge.ts@@ -7,7 +7,10 @@ import type {CanvasLoadInsightInput,} from "@posthog/core/canvas/freeformSchemas";import { canvasConnectorCallInput } from "@posthog/core/canvas/freeformSchemas";-import { invokeCanvasAction } from "@posthog/core/canvas/invokeCanvasAction";+import {+ invokeCanvasAction,+ invokeCanvasTool,+} from "@posthog/core/canvas/invokeCanvasAction";import type { QueryClient } from "@tanstack/react-query";import { hostClient } from "../hostClient";@@ -18,6 +21,8 @@ import { hostClient } from "../hostClient";// Namespace for every cached canvas read.export const CANVAS_QUERY_KEY = "canvasData/read";+const TOOL_REGISTRY_STALE_MS = 5 * 60 * 1_000;+// Deterministic stringify for cache keys: object keys are emitted in sorted order// at every depth so two reads that differ only by key order share a cache entry.// `undefined` and non-finite numbers get distinct tokens — JSON.stringify would@@ -289,6 +294,41 @@ export async function handleFreeformDataRequest((action) => client.invokeAction.mutate(action),);}+ case "toolRead":+ case "toolCall": {+ const input = payload as {+ tool?: string;+ arguments?: Record<string, unknown>;+ };+ if (!input?.tool || typeof input.tool !== "string") {+ throw new Error("ph.tools requires a tool name");+ }+ // Reads and writes into PostHog as the viewer, never cached.+ const client = hostClient().dashboards;+ const { result } = await invokeCanvasTool(+ {+ id: requireDashboardId(),+ tool: input.tool,+ arguments: input.arguments ?? {},+ },+ method === "toolCall",+ // Cached so a board that reads many flags fetches the registry once. A desktop session+ // outlives backend deploys, so the cache expires: `read_only` decides which tools skip+ // the click and the confirm.+ () =>+ queryClient.fetchQuery({+ queryKey: [CANVAS_QUERY_KEY, "tools"],+ queryFn: () => client.listTools.query(),+ staleTime: TOOL_REGISTRY_STALE_MS,+ }),+ (tool, args) =>+ window.confirm(+ `${tool.summary}\n\n${tool.name}\n${JSON.stringify(args, null, 2)}\n\nContinue?`,+ ),+ (call) => client.invokeTool.mutate(call),+ );+ return result;+ }case "connectorCall": {const dashboardId = requireDashboardId();const input = canvasConnectorCallInput.parse(payload);diff --git a/products/desktop/packages/ui/src/features/canvas/freeform/sandboxRuntime.ts b/products/desktop/packages/ui/src/features/canvas/freeform/sandboxRuntime.tsindex 42b9011c7d9e..02353ba9ab35 100644--- a/products/desktop/packages/ui/src/features/canvas/freeform/sandboxRuntime.ts+++ b/products/desktop/packages/ui/src/features/canvas/freeform/sandboxRuntime.ts@@ -324,6 +324,14 @@ export function buildSandboxDocument(actions: {invoke: (verb, payload) => call("actionInvoke", { verb, payload: payload ?? {} }),},+ // Run a PostHog MCP tool as the viewer. Every tool must be declared in+ // capabilities.posthog.tools. \`read\` takes read-only tools and may run on+ // load; \`call\` changes data, so wire it to a click (the host confirms):+ // \`ph.tools.call("feature-flag-enable", { id })\`.+ tools: {+ read: (tool, args) => call("toolRead", { tool, arguments: args ?? {} }),+ call: (tool, args) => call("toolCall", { tool, arguments: args ?? {} }),+ },// Read live third-party data with the viewer's own connection. Every// provider and tool must be declared in capabilities.connectors; the// result is cached per canvas for \`refresh\` seconds (default 60):