MCP workflow steps

MCP workflow steps let you use native Model Context Protocol (MCP) connections as first-class steps in Cofactor workflows. Connect an MCP server, describe the action you need, test it, and run it repeatedly with evidence and cached results available for review.

01When to use MCP workflow steps

Use MCP workflow steps when a workflow needs to interact with a tool or service exposed through MCP. They are useful when you want to:

• Turn exploratory work or a review into repeatable automation.
• Call an MCP tool as part of a larger workflow.
• Capture evidence that shows what the MCP step returned or changed.
• Test a connection before allowing it to run in a workflow.
• Reuse stable results during repeated runs when the underlying action does not need to execute again.

Use a regular workflow step when the action does not require an MCP connection or when you need Cofactor’s built-in browser and workflow capabilities instead.

02Core concepts

MCP connections

An MCP connection represents an authorized connection to an MCP server. The connection provides the tools and access that an MCP workflow step can use.

Create or select a connection when you add an MCP step. Keep connections scoped to the services and permissions required by the workflow, and test the connection before you publish or run the workflow.

MCP connection authentication is separate from using Claude as an MCP client. For client authentication and Claude-specific setup, see the Claude integration.

MCP workflow steps

An MCP workflow step invokes a tool through a selected MCP connection. Configure the step with the connection, the requested action, and any inputs required by that tool. Use workflow values and flow inputs for values that need to change between runs.

An MCP step can be placed alongside other workflow steps. Use its output as input to later steps when the returned information determines what the workflow should do next.

Review the step configuration before running it. Confirm that the selected connection has access to the intended resource and that inputs contain the correct environment-specific values.

Evidence and cached results

MCP steps can capture evidence from a run so you can inspect the tool response and verify the result. Use captured evidence when reviewing a run, diagnosing a failure, or documenting why a later step produced a particular outcome.

Cofactor can cache MCP results to make repeated runs more reliable and avoid unnecessary repeated work. Treat cached results as valid only for the conditions represented by the cache. Run the step again when the source data, permissions, inputs, or expected side effects have changed.

03Authoring and testing

Assisted authoring

Use assisted authoring to describe the action you want to automate and get help shaping the MCP workflow step. Provide the goal, the relevant connection, and the expected inputs or result.

Before accepting the generated configuration:

1. Confirm that the suggested MCP connection is the correct one.
2. Check the selected tool and review every input.
3. Replace example or inferred values with flow inputs or environment-specific values where appropriate.
4. Define what evidence you need to confirm that the action succeeded.
5. Save the step and test the connection before using it in a production workflow.

Assisted authoring helps create the step, but you remain responsible for reviewing its access, inputs, and expected side effects.

Testing a connection

Test an MCP connection before relying on it in a workflow run. A connection test verifies that Cofactor can reach the MCP server and use the configured access for the selected action.

Use a safe, read-only action when one is available. If the test fails, verify the connection credentials, server availability, required permissions, selected tool, and input values. Update the connection or step configuration, then test again before running the full workflow.

04Running and troubleshooting

Run the workflow normally after the MCP step passes its connection test. Open the run details to review the MCP step status, captured evidence, returned values, and any error message.

Use the following checks when a run does not produce the expected result:

• Connection failure: Test the connection again and confirm that authentication has not expired.
• Permission error: Ask for access to the specific resource or tool required by the step. Do not broaden permissions without a reason.
• Invalid input: Compare each input with the tool’s expected value and type. Check unresolved flow inputs and environment-specific values.
• Unexpected result: Review the captured evidence and confirm that the workflow used the intended connection and tool.
• Stale result: Disable or bypass the cached result by running the action again when current data or a new side effect is required.
• Intermittent failure: Retry after confirming that the MCP service is available. If the problem continues, isolate the MCP step and test it independently before retrying the complete workflow.

Keep side-effecting MCP actions isolated while troubleshooting. This makes it easier to identify the failing step and reduces the risk of repeating an unintended change.

05Best practices

• Use descriptive names for MCP connections and workflow steps.
• Prefer read-only connection tests and safe test inputs.
• Grant only the permissions the workflow needs.
• Keep credentials and environment-specific values in the connection or flow configuration rather than embedding them in prompts or fixed inputs.
• Capture evidence that proves the outcome, not just that the tool was called.
• Review cached results when validating a run, and rerun the action when freshness matters.
• Add validation after side-effecting steps so the workflow confirms the change it intended to make.
• Keep MCP actions small and focused. Split unrelated actions into separate steps so each result is easier to test and troubleshoot.
• Re-test connections after changing authentication, permissions, server configuration, or tool inputs.

06Related

• Claude integration — configure Claude as an MCP client.
• Workflow reference — learn about workflow structure and execution.
• Spec reviews — start from observed behavior or requirements and promote a review into a draft workflow.