CmdForge

An McpStep lets a normal CmdForge pipeline cross into an MCP server, capture a typed result, and continue. Think of it as a network-aware cousin of ToolStep: the server owns the capability; your tool owns the workflow.

Add a Local Stdio Server

Arguments are repeated deliberately. CmdForge never asks a shell to reinterpret this command:

cmdforge mcp add filesystem   --transport stdio   --command npx   --arg=-y   --arg @modelcontextprotocol/server-filesystem   --arg "$HOME/Documents"   --description "Read approved documents"

Test the handshake and see the server's declared schemas:

cmdforge mcp list
cmdforge mcp connect filesystem

Add a Streamable HTTP Server

export WEATHER_MCP_TOKEN="..."

cmdforge mcp add weather   --transport streamable-http   --url https://weather.example.com/mcp   --header 'Authorization=Bearer ${WEATHER_MCP_TOKEN}'   --timeout 20

Environment references are resolved only when connecting. The token does not need to live in mcp.yaml. Remote endpoints must use HTTPS; loopback development servers may use HTTP.

What CmdForge Stores

version: 1
servers:
  filesystem:
    transport: stdio
    command: npx
    args: [-y, "@modelcontextprotocol/server-filesystem", "/home/you/Documents"]
    timeout: 30
    approved: true

  weather:
    transport: streamable-http
    url: https://weather.example.com/mcp
    headers:
      Authorization: "Bearer ${WEATHER_MCP_TOKEN}"
    timeout: 20
    approved: true

The file is written with mode 0600. Stdio entries may also specify cwd, env, and a narrow inherit_env list.

Put the Call in a Tool

steps:
  - type: mcp
    name: fetch-forecast
    server: weather
    tool: weather_current
    arguments:
      city: "{city}"
      units: metric
    output_var: forecast
    result_mode: structured

  - type: prompt
    provider: ollama
    prompt: |
      Explain this forecast for a cyclist:
      {forecast}
    output_var: advice

output: "{advice.output}"

Argument substitution preserves types: a variable containing a number or object stays a number or object when it occupies the entire value.

Choose a Result Mode

Mode	Use it when
`auto`	You want structured content when present and a sensible content fallback.
`structured`	Downstream steps require the server's structured result.
`content`	You need the MCP content-block representation.
`text`	You want text blocks flattened into ordinary text.

An MCP isError result becomes a CmdForge failure; it is not disguised as successful text.

Operate Deliberately

cmdforge mcp connect weather   # rediscover and verify
cmdforge mcp remove weather    # remove configuration

Connections are invocation-scoped and cleaned up after discovery or execution. CmdForge caches schemas during a run, not a permanent background server process.

Calling MCP Servers from a Pipeline