feat(mcp-server): expose workflow tools in Forest MCP server (PRD-49)

packages/agent-testing/src/forest-admin-client-mock.ts

@@ -44,7 +44,7 @@
 export default class ForestAdminClientMock implements ForestAdminClient {
   readonly chartHandler: ChartHandlerInterface;
   readonly contextVariablesInstantiator: ContextVariablesInstantiatorInterface = {
     buildContextVariables: () => ({} as any), // TODO: return actual context variables
   };
 
   readonly modelCustomizationService: ModelCustomizationService;
@@ -62,8 +62,15 @@
     updateActivityLogStatus: () => Promise.resolve(),
   };
 
+  readonly workflowsService: ForestAdminClient['workflowsService'] = {
+    listMcpEnabledWorkflows: () => Promise.resolve([]),
+    triggerMcpWorkflow: () => Promise.resolve({ runId: '1', runState: 'loading' }),
+    getMcpWorkflowRun: () =>
+      Promise.resolve({ runState: 'loading', currentStep: null, waitingForHumanInput: false }),
+  };
+
   readonly permissionService: any;
   readonly authService: any;
 
   constructor() {
     this.permissionService = {

packages/agent-testing/test/forest-admin-client-mock.test.ts

@@ -0,0 +1,45 @@
+import ForestAdminClientMock from '../src/forest-admin-client-mock';
+
+describe('ForestAdminClientMock', () => {
+  describe('workflowsService', () => {
+    it('should resolve an empty list of MCP-enabled workflows', async () => {
+      const client = new ForestAdminClientMock();
+
+      await expect(
+        client.workflowsService.listMcpEnabledWorkflows({
+          forestServerToken: 'token',
+          renderingId: '1',
+        }),
+      ).resolves.toEqual([]);
+    });
+
+    it('should resolve a loading run when triggering a workflow', async () => {
+      const client = new ForestAdminClientMock();
+
+      await expect(
+        client.workflowsService.triggerMcpWorkflow({
+          forestServerToken: 'token',
+          renderingId: '1',
+          workflowId: 'wf-1',
+          recordId: '42',
+        }),
+      ).resolves.toEqual({ runId: '1', runState: 'loading' });
+    });
+
+    it('should resolve a loading run status when fetching a workflow run', async () => {
+      const client = new ForestAdminClientMock();
+
+      await expect(
+        client.workflowsService.getMcpWorkflowRun({
+          forestServerToken: 'token',
+          renderingId: '1',
+          runId: '1',
+        }),
+      ).resolves.toEqual({
+        runState: 'loading',
+        currentStep: null,
+        waitingForHumanInput: false,
+      });
+    });
+  });
+});

packages/agent/src/agent.ts

@@ -376,6 +376,7 @@ export default class Agent<S extends TSchema = TSchema> extends FrameworkMounter
       const forestServerClient = new ForestServerClientImpl(
         this.options.forestAdminClient.schemaService,
         this.options.forestAdminClient.activityLogsService,
+        this.options.forestAdminClient.workflowsService,
         this.options.forestServerUrl,
       );
 

packages/agent/test/__factories__/forest-admin-client.ts

@@ -54,6 +54,11 @@ const forestAdminClientFactory = ForestAdminClientFactory.define(() => ({
     createMcpActivityLog: jest.fn(),
     updateActivityLogStatus: jest.fn(),
   },
+  workflowsService: {
+    listMcpEnabledWorkflows: jest.fn(),
+    triggerMcpWorkflow: jest.fn(),
+    getMcpWorkflowRun: jest.fn(),
+  },
   subscribeToServerEvents: jest.fn(),
   close: jest.fn(),
   onRefreshCustomizations: jest.fn(),

packages/forestadmin-client/src/build-application-services.ts

@@ -22,6 +22,7 @@ import UserPermissionService from './permissions/user-permission';
 import SchemaService from './schema';
 import ContextVariablesInstantiator from './utils/context-variables-instantiator';
 import defaultLogger from './utils/default-logger';
+import WorkflowsService from './workflows';
 
 export default function buildApplicationServices(
   forestAdminServerInterface: ForestAdminServerInterface,
@@ -31,6 +32,7 @@ export default function buildApplicationServices(
   renderingPermission: RenderingPermissionService;
   schema: SchemaService;
   activityLogs: ActivityLogsService;
+  workflows: WorkflowsService;
   contextVariables: ContextVariablesInstantiator;
   ipWhitelist: IpWhiteListService;
   permission: PermissionService;
@@ -89,6 +91,7 @@ export default function buildApplicationServices(
     ipWhitelist: new IpWhiteListService(forestAdminServerInterface, optionsWithDefaults),
     schema: new SchemaService(forestAdminServerInterface, optionsWithDefaults),
     activityLogs: new ActivityLogsService(forestAdminServerInterface, optionsWithDefaults),
+    workflows: new WorkflowsService(forestAdminServerInterface, optionsWithDefaults),
     auth: forestAdminServerInterface.makeAuthService(optionsWithDefaults),
     modelCustomizationService: new ModelCustomizationFromApiService(
       forestAdminServerInterface,

packages/forestadmin-client/src/forest-admin-client-with-cache.ts

@@ -19,6 +19,7 @@ import type {
   PermissionService,
 } from './types';
 import type ContextVariablesInstantiator from './utils/context-variables-instantiator';
+import type WorkflowsService from './workflows';
 
 import verifyAndExtractApproval from './permissions/verify-approval';
 
@@ -32,6 +33,7 @@ export default class ForestAdminClientWithCache implements ForestAdminClient {
     protected readonly ipWhitelistService: IpWhiteListService,
     public readonly schemaService: SchemaService,
     public readonly activityLogsService: ActivityLogsService,
+    public readonly workflowsService: WorkflowsService,
     public readonly authService: ForestAdminAuthServiceInterface,
     public readonly modelCustomizationService: ModelCustomizationService,
     public readonly mcpServerConfigService: McpServerConfigService,

packages/forestadmin-client/src/index.ts

@@ -28,8 +28,17 @@ export {
   ActivityLogType,
   CreateActivityLogParams,
   UpdateActivityLogStatusParams,
+  McpWorkflow,
+  ListMcpWorkflowsParams,
+  TriggerMcpWorkflowParams,
+  GetMcpWorkflowRunParams,
+  WorkflowRunState,
+  WorkflowRunStep,
+  WorkflowRunStatus,
+  WorkflowRunTriggerResult,
   // Service interfaces for MCP
   ActivityLogsServiceInterface,
+  WorkflowsServiceInterface,
   SchemaServiceInterface,
 } from './types';
 export { IpWhitelistConfiguration } from './ip-whitelist/types';
@@ -55,6 +64,7 @@ export default function createForestAdminClient(
     ipWhitelist,
     schema,
     activityLogs,
+    workflows,
     auth,
     modelCustomizationService,
     mcpServerConfigService,
@@ -71,6 +81,7 @@ export default function createForestAdminClient(
     ipWhitelist,
     schema,
     activityLogs,
+    workflows,
     auth,
     modelCustomizationService,
     mcpServerConfigService,
@@ -94,6 +105,7 @@ export { default as ServerUtils } from './utils/server';
 // export is necessary for the agent-generator package
 export { default as SchemaService, SchemaServiceOptions } from './schema';
 export { default as ActivityLogsService, ActivityLogsOptions } from './activity-logs';
+export { default as WorkflowsService, WorkflowsServiceOptions } from './workflows';
 
 export * from './auth/errors';
 export * from './utils/errors';

packages/forestadmin-client/src/permissions/forest-http-api.ts

@@ -9,6 +9,9 @@ import type {
   ForestAdminServerInterface,
   ForestSchemaCollection,
   IpWhitelistRulesResponse,
+  McpWorkflow,
+  WorkflowRunStatus,
+  WorkflowRunTriggerResult,
 } from '../types';
 import type { HttpOptions } from '../utils/http-options';
 
@@ -151,4 +154,57 @@ export default class ForestHttpApi implements ForestAdminServerInterface {
       headers: options.headers,
     });
   }
+
+  async listMcpEnabledWorkflows(
+    options: ActivityLogHttpOptions,
+    renderingId: string,
+    collectionName?: string,
+  ): Promise<McpWorkflow[]> {
+    const query = collectionName ? `?collectionName=${encodeURIComponent(collectionName)}` : '';
+
+    return ServerUtils.queryWithBearerToken<McpWorkflow[]>({
+      forestServerUrl: options.forestServerUrl,
+      method: 'get',
+      path: `/api/workflow-orchestrator/mcp-workflows${query}`,
+      bearerToken: options.bearerToken,
+      headers: { 'forest-rendering-id': renderingId, ...options.headers },
+    });
+  }
+
+  async triggerMcpWorkflow(
+    options: ActivityLogHttpOptions,
+    renderingId: string,
+    workflowId: string,
+    recordId: string,
+  ): Promise<WorkflowRunTriggerResult> {
+    // The orchestrator returns a numeric runId; normalize it to the string form expected by
+    // getMcpWorkflowRun. workflowName/collectionName are passed through when present so the
+    // caller can label the audit log without listing every workflow first.
+    const result = await ServerUtils.queryWithBearerToken<
+      Omit<WorkflowRunTriggerResult, 'runId'> & { runId: number | string }
+    >({
+      forestServerUrl: options.forestServerUrl,
+      method: 'post',
+      path: `/api/workflow-orchestrator/mcp-workflows/${encodeURIComponent(workflowId)}/start`,
+      bearerToken: options.bearerToken,
+      body: { recordId },
+      headers: { 'forest-rendering-id': renderingId, ...options.headers },
+    });
+
+    return { ...result, runId: String(result.runId) };
+  }
+
+  async getMcpWorkflowRun(
+    options: ActivityLogHttpOptions,
+    renderingId: string,
+    runId: string,
+  ): Promise<WorkflowRunStatus> {
+    return ServerUtils.queryWithBearerToken<WorkflowRunStatus>({
+      forestServerUrl: options.forestServerUrl,
+      method: 'get',
+      path: `/api/workflow-orchestrator/mcp-workflows/runs/${encodeURIComponent(runId)}`,
+      bearerToken: options.bearerToken,
+      headers: { 'forest-rendering-id': renderingId, ...options.headers },
+    });
+  }
 }

packages/forestadmin-client/src/types.ts

@@ -53,6 +53,7 @@ export interface ForestAdminClient {
   readonly authService: ForestAdminAuthServiceInterface;
   readonly schemaService: SchemaServiceInterface;
   readonly activityLogsService: ActivityLogsServiceInterface;
+  readonly workflowsService: WorkflowsServiceInterface;
 
   verifySignedActionParameters<TSignedParameters>(signedParameters: string): TSignedParameters;
 
@@ -252,7 +253,8 @@ export type ActivityLogAction =
   | 'update'
   | 'delete'
   | 'listRelatedData'
-  | 'describeCollection';
+  | 'describeCollection'
+  | 'triggerWorkflow';
 
 export type ActivityLogType = 'read' | 'write';
 
@@ -282,6 +284,81 @@ export interface ActivityLogsServiceInterface {
   updateActivityLogStatus: (params: UpdateActivityLogStatusParams) => Promise<void>;
 }
 
+/**
+ * An MCP-enabled workflow, as returned by the Forest server's workflow listing endpoint.
+ */
+export interface McpWorkflow {
+  workflowId: string;
+  name: string;
+  collectionName: string | null;
+}
+
+export interface ListMcpWorkflowsParams {
+  forestServerToken: string;
+  renderingId: string;
+  collectionName?: string;
+}
+
+/**
+ * The lifecycle state of a workflow run, as persisted by the orchestrator.
+ */
+export type WorkflowRunState = 'started' | 'pending' | 'loading' | 'aborted' | 'finished';
+
+/**
+ * The outcome of starting a workflow run: the run continues asynchronously server-side.
+ * `runId` is normalized to a string so it can be fed back to `getMcpWorkflowRun` as-is.
+ * `workflowName`/`collectionName` are echoed by the start endpoint to build the audit label
+ * without a second round-trip; they are optional so older servers degrade gracefully.
+ */
+export interface WorkflowRunTriggerResult {
+  runId: string;
+  runState: WorkflowRunState;
+  workflowName?: string;
+  collectionName?: string | null;
+}
+
+export interface TriggerMcpWorkflowParams {
+  forestServerToken: string;
+  renderingId: string;
+  workflowId: string;
+  recordId: string;
+}
+
+/**
+ * The step a run is currently on, as derived server-side from the workflow history.
+ */
+export interface WorkflowRunStep {
+  name: string;
+  type: string;
+}
+
+/**
+ * The normalized status of a workflow run, as exposed for external (MCP) consumption.
+ * `result` is the terminal output when finished; `error` the failure detail otherwise.
+ */
+export interface WorkflowRunStatus {
+  runState: WorkflowRunState;
+  currentStep: WorkflowRunStep | null;
+  waitingForHumanInput: boolean;
+  result?: unknown;
+  error?: unknown;
+}
+
+export interface GetMcpWorkflowRunParams {
+  forestServerToken: string;
+  renderingId: string;
+  runId: string;
+}
+
+/**
+ * Service interface for workflow operations (MCP-related).
+ */
+export interface WorkflowsServiceInterface {
+  listMcpEnabledWorkflows: (params: ListMcpWorkflowsParams) => Promise<McpWorkflow[]>;
+  triggerMcpWorkflow: (params: TriggerMcpWorkflowParams) => Promise<WorkflowRunTriggerResult>;
+  getMcpWorkflowRun: (params: GetMcpWorkflowRunParams) => Promise<WorkflowRunStatus>;
+}
+
 /**
  * Service interface for schema operations (extended for MCP).
  */
@@ -320,6 +397,24 @@ export interface ForestAdminServerInterface {
     id: string,
     body: object,
   ) => Promise<void>;
+
+  // Workflow operations
+  listMcpEnabledWorkflows?: (
+    options: ActivityLogHttpOptions,
+    renderingId: string,
+    collectionName?: string,
+  ) => Promise<McpWorkflow[]>;
+  triggerMcpWorkflow?: (
+    options: ActivityLogHttpOptions,
+    renderingId: string,
+    workflowId: string,
+    recordId: string,
+  ) => Promise<WorkflowRunTriggerResult>;
+  getMcpWorkflowRun?: (
+    options: ActivityLogHttpOptions,
+    renderingId: string,
+    runId: string,
+  ) => Promise<WorkflowRunStatus>;
 }
 
 export type ActivityLogHttpOptions = {