Step MCP

Quick Answer

Use flow/step :mcp when the flow should deterministically call one named
tool on a configured remote MCP adapter. Use :tools {:mcp [...]} on :llm or
:agent when the model or agent should decide if and when to call the MCP
tool.

Outbound MCP steps support Streamable HTTP MCP endpoints only. The remote MCP
server is still bound through a normal :http-api requirement with
:backend :mcp, so connection auth, base URL validation, SSRF protection, and
installation binding stay on the existing connection path.

Example

{:requires [{:slot :linear-mcp
             :type :http-api
             :label "Linear MCP"
             :backend :mcp
             :base-url "https://mcp.linear.app"
             :auth {:type :bearer}}]

 :mcp [{:id :linear/issues
        :connection :linear-mcp
        :transport :streamable-http
        :allow-tools ["list_issues" "get_issue"]
        :deny-tools ["delete_issue"]
        :tool-prefix "linear"
        :timeout-ms 15000
        :max-result-bytes 200000}]

 :flow
 '(let [issues (flow/step :mcp :fetch-linear-issues
                 {:adapter :linear/issues
                  :tool "list_issues"
                  :arguments {:team_id (-> (flow/input) :team-id)}})]
    issues)}

The step sends a JSON-RPC tools/call request to the configured MCP endpoint.
The result shape matches agentic MCP tool calls:

{:mcp/tool "list_issues"
 :mcp/adapter-id :linear/issues
 :mcp/transport :streamable-http
 :mcp/is-error false
 :content "..."
 :result {...}
 :status 200}

Fields

Field	Type	Required	Notes
`:adapter`	keyword/string	Yes	Top-level `:mcp` adapter id, such as `:linear/issues`.
`:server`	keyword/string	No	Compatibility alias for `:adapter`; can also match the adapter connection slot. Prefer `:adapter` in new flows.
`:tool`	string/keyword	Yes	Remote MCP tool name. Hyphens are normalized to underscores for parity with agentic MCP tool refs.
`:tool-name`	string/keyword	No	Alias for `:tool`.
`:arguments`	map	No	JSON-object-shaped arguments passed to the MCP tool. Defaults to `{}`.
`:input`	map	No	Alias for `:arguments`. Prefer `:arguments` in new flows.
`:timeout-ms`	int	No	Per-call timeout override in milliseconds. Defaults to adapter `:timeout-ms`, then 190000.
`:max-result-bytes`	int	No	Per-call response-size override. Defaults to adapter `:max-result-bytes`, then 200000.

Common step options such as :retry, :timeout, :on-error, :persist,
:review, and :confirm are also accepted.

Use the authored step shape above in flow definitions. Normalized MCP activity
fields such as :connection plus :mcp-tool-name are internal runtime payloads
used by agentic MCP tools, and are not a public flow/step :mcp source shape.
When both are present through runtime internals, the authored step path resolves
the top-level adapter and enforces its allow/deny policy before any remote call.

:timeout is the common step/activity timeout in seconds. :timeout-ms is the
MCP HTTP client timeout sent to the Streamable HTTP call. If :timeout is set
on the step, it is preserved as the activity timeout instead of being replaced
by the adapter :timeout-ms default.

Adapter Requirements

Declare remote MCP servers in the top-level :mcp adapter list. The adapter
connects the flow to a normal :http-api requirement:

:requires [{:slot :meta-mcp
            :type :http-api
            :label "Meta Marketing MCP"
            :backend :mcp
            :base-url "https://example-mcp-host.invalid/mcp"
            :auth {:type :bearer}
            :provided-by :installer}]

:mcp [{:id :meta/marketing
       :connection :meta-mcp
       :transport :streamable-http
       :allow-tools ["ads_insights_performance_trend"
                     "ads_get_ad_entities"]
       :deny-tools ["ads_update_entity"
                    "ads_create_campaign"]}]

flow/step :mcp calls exactly the named tool. If the adapter has
:allow-tools, the step tool must be in that list. If the adapter has
:deny-tools, denied tools are rejected even when called directly.

Choosing MCP Step Vs Agentic MCP Tools

Prefer flow/step :mcp when:

The flow author knows the exact MCP tool to call.
The call belongs in deterministic orchestration.
The tool arguments are produced by previous steps or flow input.
You want retries, :on-error, persistence, and checkpoints around one known
remote operation.

Prefer :tools {:mcp [...]} on :llm or :agent when:

The model should choose whether to call the MCP tool.
The agent may need to call the tool multiple times while investigating.
The MCP tool is one capability among other agent tools.
You want model-visible tool schemas and agentic tool-loop tracing.

Both patterns use the same top-level :mcp adapters and the same HTTP MCP
runtime client.

Limits And Security

Only :transport :streamable-http is supported for outbound flow runtime.
Local stdio MCP servers are not launched from flows.
Connections must use the :http-api requirement path with :backend :mcp.
MCP responses are bounded by :max-result-bytes.
Remote tool metadata is not needed for direct :mcp steps. For agentic MCP
tools, remote descriptions/schema annotations remain untrusted unless the
adapter or tool sets :trusted-metadata true after review.