Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(mcp-host): enforce the workflow step tool allowlist at call time

Jose Ramirez67e7a99b2b1f
diff --git a/mcp-host/src/workflow/__tests__/workflowService.security.test.ts b/mcp-host/src/workflow/__tests__/workflowService.security.test.ts
index a23856c1d..2a84ccd12 100644
--- a/mcp-host/src/workflow/__tests__/workflowService.security.test.ts
+++ b/mcp-host/src/workflow/__tests__/workflowService.security.test.ts
@@ -1,7 +1,9 @@
-import { describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
import { LlmErrorCode } from '../../core/errors'
import type { SingleTurnProvider } from '../../llm'
-import type { McpClientConnection } from '../stepRouter'
+import { INTERNAL_TOOLS } from '../internalTools'
+import { type McpClientConnection, StepMcpRouter } from '../stepRouter'
+import type { AllowedToolsConfig, ExecuteStepRequest } from '../types'
import { WorkflowService } from '../workflowService'
// ─── Mock Factories ─────────────────────────────────────────────────────
@@ -45,10 +47,12 @@ function mockLlmFactory(provider?: SingleTurnProvider) {
provider ?? mockLlmProvider([{ content: 'ok' }])
}
-function mockMcpClient(): McpClientConnection {
+function mockMcpClient(
+ tools: Array<{ name: string; description?: string }> = []
+): McpClientConnection {
return {
connect: vi.fn().mockResolvedValue(undefined),
- listTools: vi.fn().mockResolvedValue([]),
+ listTools: vi.fn().mockResolvedValue(tools),
callTool: vi.fn().mockResolvedValue({ content: 'result', isError: false }),
disconnect: vi.fn().mockResolvedValue(undefined),
}
@@ -381,3 +385,234 @@ describe('LLM auth error detection and diagnostics', () => {
expect(result.error).toBe('Connection timeout after 30000ms')
})
})
+
+// ─── Spec §3.1.2: workflow tool allowlist enforced at call time ─────────
+
+describe('workflow tool allowlist enforced at call time (spec §3.1.2)', () => {
+ const FINAL_TEXT = 'Review complete: no blocking issues found.'
+ // Schema-valid for the module-level INTERNAL_TOOLS read/trigger definitions
+ // (required: namespace + name), so a regression reaches execute() instead of
+ // being stopped early by argument validation.
+ const FOREIGN_WORKFLOW_ARGS = { namespace: 'sandbox-recipes', name: 'other-recipe' }
+ const PR_REVIEW_ALLOWLIST: AllowedToolsConfig = { include: ['srv__read'] }
+
+ const notAllowed = (toolName: string) =>
+ `Tool '${toolName}' is not allowed in this step and was not run. Use only the tools provided for this step.`
+
+ type ScriptedCall = { name: string; arguments: Record<string, unknown> }
+
+ afterEach(() => {
+ vi.restoreAllMocks()
+ })
+
+ function spyInternalExecute(name: string) {
+ const tool = INTERNAL_TOOLS.find(t => t.name === name)
+ if (!tool) throw new Error(`INTERNAL_TOOLS has no ${name}`)
+ return vi
+ .spyOn(tool, 'execute')
+ .mockResolvedValue({ success: true, content: `${name} executed` })
+ }
+
+ // Server `srv` exposes [read, write]. The fake provider answers the first
+ // turn with `toolCalls` (if any) and the next turn with FINAL_TEXT.
+ function harness(toolCalls: ScriptedCall[]) {
+ const client = mockMcpClient([{ name: 'read' }, { name: 'write' }])
+ const llm = mockLlmProvider(
+ toolCalls.length > 0
+ ? [
+ { content: null, tool_calls: toolCalls },
+ { content: FINAL_TEXT, tool_calls: null },
+ ]
+ : [{ content: FINAL_TEXT, tool_calls: null }]
+ )
+ const svc = new WorkflowService('test', {
+ llmFactory: mockLlmFactory(llm),
+ mcpClientFactory: () => client,
+ })
+ svc.configure({ provider: 'openai', model: 'gpt-4', apiKey: 'k' })
+ return { client, llm, svc }
+ }
+
+ function runStep(
+ svc: WorkflowService,
+ allowedTools?: AllowedToolsConfig,
+ extra: Partial<ExecuteStepRequest> = {}
+ ) {
+ return svc.executeStep({
+ stepId: 'review',
+ instruction: 'Review the pull request.',
+ mcpServers: [{ name: 'srv', url: 'http://srv' }],
+ ...(allowedTools ? { allowedTools } : {}),
+ ...extra,
+ })
+ }
+
+ function providerCall(llm: SingleTurnProvider, index: number) {
+ const calls = vi.mocked(llm.completeSingleTurnWithTools).mock.calls
+ expect(calls.length, `provider was called ${calls.length} times`).toBeGreaterThan(index)
+ return {
+ messages: calls[index][0] as Array<{ role: string; content: string }>,
+ tools: calls[index][1] as Array<{ name: string }>,
+ }
+ }
+
+ // The model sees each tool result as `<tool-result server="<name>" …>\n<json>\n</tool-result>`
+ // on the turn after the call (workflowService.ts executeStep tool loop).
+ function toolResultSeenByModel(llm: SingleTurnProvider, toolName: string): unknown {
+ const { messages } = providerCall(llm, 1)
+ const prefix = `<tool-result server="${toolName}" data-only="true">\n`
+ const suffix = '\n</tool-result>'
+ const message = messages.find(m => m.role === 'user' && m.content.startsWith(prefix))
+ expect(message, `the model never received a tool result for ${toolName}`).toBeDefined()
+ const content = message?.content ?? ''
+ return JSON.parse(content.slice(prefix.length, content.length - suffix.length))
+ }
+
+ it.each<[string, Record<string, unknown>]>([
+ ['srv__write', { path: 'README.md', content: 'pwned' }],
+ ['clerum__trigger_workflow', FOREIGN_WORKFLOW_ARGS],
+ ['clerum__read_workflow', FOREIGN_WORKFLOW_ARGS],
+ ])(
+ 'never runs %s outside include, returns a tool error to the model, and completes the step',
+ async (toolName, args) => {
+ const triggerExecute = spyInternalExecute('clerum__trigger_workflow')
+ const readExecute = spyInternalExecute('clerum__read_workflow')
+ const { client, llm, svc } = harness([{ name: toolName, arguments: args }])
+
+ const result = await runStep(svc, PR_REVIEW_ALLOWLIST)
+
+ expect(result.status).toBe('completed')
+ expect(result.output).toBe(FINAL_TEXT)
+ expect(client.callTool).not.toHaveBeenCalled()
+ expect(triggerExecute).not.toHaveBeenCalled()
+ expect(readExecute).not.toHaveBeenCalled()
+ expect(providerCall(llm, 0).tools.map(t => t.name)).toEqual(['srv__read'])
+ expect(toolResultSeenByModel(llm, toolName)).toEqual({
+ success: false,
+ error: notAllowed(toolName),
+ })
+ expect(result.toolsCalled?.map(r => r.result)).toEqual([
+ { success: false, error: notAllowed(toolName) },
+ ])
+ }
+ )
+
+ it('rejects every forbidden call in one turn while the allowlisted call still dispatches', async () => {
+ const triggerExecute = spyInternalExecute('clerum__trigger_workflow')
+ const readExecute = spyInternalExecute('clerum__read_workflow')
+ const { client, llm, svc } = harness([
+ { name: 'srv__write', arguments: { path: 'README.md', content: 'pwned' } },
+ { name: 'clerum__trigger_workflow', arguments: FOREIGN_WORKFLOW_ARGS },
+ { name: 'clerum__read_workflow', arguments: FOREIGN_WORKFLOW_ARGS },
+ { name: 'srv__read', arguments: { path: 'README.md' } },
+ ])
+
+ const result = await runStep(svc, PR_REVIEW_ALLOWLIST)
+
+ expect(result.status).toBe('completed')
+ expect(result.output).toBe(FINAL_TEXT)
+ expect(client.callTool).toHaveBeenCalledTimes(1)
+ expect(client.callTool).toHaveBeenCalledWith(
+ 'read',
+ { path: 'README.md' },
+ expect.objectContaining({ signal: expect.any(Object), timeoutMs: expect.any(Number) })
+ )
+ expect(triggerExecute).not.toHaveBeenCalled()
+ expect(readExecute).not.toHaveBeenCalled()
+ for (const toolName of ['srv__write', 'clerum__trigger_workflow', 'clerum__read_workflow']) {
+ expect(toolResultSeenByModel(llm, toolName)).toEqual({
+ success: false,
+ error: notAllowed(toolName),
+ })
+ }
+ expect(toolResultSeenByModel(llm, 'srv__read')).toBe('result')
+ })
+
+ it('still runs an internal tool the allowlist names', async () => {
+ const listExecute = spyInternalExecute('clerum__list_workflows')
+ const { client, llm, svc } = harness([{ name: 'clerum__list_workflows', arguments: {} }])
+
+ const result = await runStep(svc, { include: ['srv__read', 'clerum__list_workflows'] })
+
+ expect(result.status).toBe('completed')
+ expect(listExecute).toHaveBeenCalledTimes(1)
+ expect(client.callTool).not.toHaveBeenCalled()
+ expect(providerCall(llm, 0).tools.map(t => t.name)).toEqual([
+ 'clerum__list_workflows',
+ 'srv__read',
+ ])
+ expect(toolResultSeenByModel(llm, 'clerum__list_workflows')).toEqual({
+ success: true,
+ content: 'clerum__list_workflows executed',
+ })
+ })
+
+ it('registers only the internal tools the allowlist names', async () => {
+ const register = vi.spyOn(StepMcpRouter.prototype, 'registerInternalTools')
+ const { svc } = harness([])
+
+ const result = await runStep(svc, { include: ['srv__read', 'clerum__list_workflows'] })
+
+ expect(result.status).toBe('completed')
+ expect(register).toHaveBeenCalledTimes(1)
+ expect(register.mock.calls[0][0].map(t => t.name)).toEqual(['clerum__list_workflows'])
+ })
+
+ it.each<[string, AllowedToolsConfig | undefined]>([
+ ['absent', undefined],
+ ['empty', { include: [] }],
+ ])(
+ "keeps today's behaviour when allowedTools.include is %s: every tool is registered, offered and callable",
+ async (_label, allowedTools) => {
+ const register = vi.spyOn(StepMcpRouter.prototype, 'registerInternalTools')
+ const listExecute = spyInternalExecute('clerum__list_workflows')
+ const { client, llm, svc } = harness([
+ { name: 'srv__write', arguments: { path: 'notes.md' } },
+ { name: 'clerum__list_workflows', arguments: {} },
+ ])
+
+ const result = await runStep(svc, allowedTools)
+
+ expect(result.status).toBe('completed')
+ expect(client.callTool).toHaveBeenCalledWith(
+ 'write',
+ { path: 'notes.md' },
+ expect.objectContaining({ signal: expect.any(Object) })
+ )
+ expect(listExecute).toHaveBeenCalledTimes(1)
+ const workflowAndCapabilityTools = [
+ 'clerum__list_workflows',
+ 'clerum__read_workflow',
+ 'clerum__trigger_workflow',
+ 'clerum__get_capabilities',
+ 'clerum__generate_markdown',
+ ]
+ expect(register.mock.calls[0][0].map(t => t.name)).toEqual(
+ expect.arrayContaining(workflowAndCapabilityTools)
+ )
+ expect(providerCall(llm, 0).tools.map(t => t.name)).toEqual(
+ expect.arrayContaining(['srv__read', 'srv__write', ...workflowAndCapabilityTools])
+ )
+ }
+ )
+
+ it('keeps failing the step on an unknown tool name when no allowlist is in effect', async () => {
+ const { client, svc } = harness([{ name: 'ghost__tool', arguments: {} }])
+
+ const result = await runStep(svc)
+
+ expect(result.status).toBe('failed')
+ expect(result.error).toContain("Unknown tool: 'ghost__tool'")
+ expect(client.callTool).not.toHaveBeenCalled()
+ })
+
+ it('does not let a rejected call satisfy toolChoice=required', async () => {
+ const { client, svc } = harness([{ name: 'srv__write', arguments: { path: 'README.md' } }])
+
+ const result = await runStep(svc, PR_REVIEW_ALLOWLIST, { toolChoice: 'required' })
+
+ expect(result.status).toBe('failed')
+ expect(result.error).toBe(`required-tool-call-failed: srv__write: ${notAllowed('srv__write')}`)
+ expect(client.callTool).not.toHaveBeenCalled()
+ })
+})
diff --git a/mcp-host/src/workflow/types.ts b/mcp-host/src/workflow/types.ts
index a1d2acb8d..785a849aa 100644
--- a/mcp-host/src/workflow/types.ts
+++ b/mcp-host/src/workflow/types.ts
@@ -16,8 +16,19 @@ export interface StepMcpServerRef {
// ─── Tool Scoping ───────────────────────────────────────────────────────
+/**
+ * Step tool allowlist (spec §3.1.2).
+ *
+ * - include absent or empty: no allowlist. A step that declares MCP servers is
+ * offered, and may call, every registered tool (all MCP tools plus the
+ * clerum__* internal tools; GFS tools still need their own opt-in). A step
+ * with no MCP servers is text-only and gets no tools.
+ * - include non-empty: the complete toolset. Only listed tools are registered
+ * (clerum__* included) and offered. A call to any other name returns a
+ * recoverable tool-error result to the model and is never executed.
+ */
export interface AllowedToolsConfig {
- include?: string[] // if present and non-empty: ONLY these tools exposed
+ include?: string[] // if present and non-empty: ONLY these tools exposed AND callable
}
// ─── Execute Step ───────────────────────────────────────────────────────
diff --git a/mcp-host/src/workflow/workflowService.ts b/mcp-host/src/workflow/workflowService.ts
index af49e8e09..00446d1b8 100644
--- a/mcp-host/src/workflow/workflowService.ts
+++ b/mcp-host/src/workflow/workflowService.ts
@@ -900,6 +900,14 @@ export class WorkflowService {
}
const router = new StepMcpRouter(this.mcpClientFactory)
+
+ // Spec §3.1.2: a non-empty allowedTools.include is the step's complete
+ // toolset. Absent/empty keeps today's behaviour: every registered tool is
+ // offered when the step declares MCP servers, and none for a text-only step.
+ const allowedToolNames =
+ Array.isArray(req.allowedTools?.include) && req.allowedTools.include.length > 0
+ ? new Set(req.allowedTools.include)
+ : null
// Register internal output tools (clerum__*) — available to all
// workflow steps. Also register clerum__get_capabilities so workflow
// steps can branch on which integrations the operator has set up.
@@ -1112,7 +1120,17 @@ export class WorkflowService {
].filter(tool => requestedGfsToolNames.has(tool.name))
internalTools.push(...scopedGfsTools)
}
- router.registerInternalTools(internalTools, getOutputDir())
+ // Register an internal tool only when the allowlist names it (extends the
+ // GFS opt-in above to every clerum__* tool), and reject calls to anything
+ // outside the offered set at dispatch time. Both are no-ops without an
+ // allowlist.
+ router.registerInternalTools(
+ allowedToolNames
+ ? internalTools.filter(tool => allowedToolNames.has(tool.name))
+ : internalTools,
+ getOutputDir()
+ )
+ router.setAllowedTools(req.allowedTools)
// 1. Connect to step-declared MCP servers
await router.connect(req.mcpServers ?? [], {
@@ -1124,8 +1142,7 @@ export class WorkflowService {
// unless the recipe explicitly allows them; otherwise analysis steps can
// loop on premature file-generation calls.
const hasDeclaredMcpServers = (req.mcpServers ?? []).length > 0
- const hasExplicitAllowedTools =
- Array.isArray(req.allowedTools?.include) && req.allowedTools.include.length > 0
+ const hasExplicitAllowedTools = allowedToolNames !== null
const tools =
hasDeclaredMcpServers || hasExplicitAllowedTools
? router.getFilteredTools(req.allowedTools)