Skip to content

: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.

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.html
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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: z
diff --git a/products/desktop/packages/ui/src/features/canvas/freeform/BuiltCanvas.test.tsx b/products/desktop/packages/ui/src/features/canvas/freeform/BuiltCanvas.test.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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):