Declare a unified operation

A unified operation is one logical SDK or MCP operation that calls several provider operations, waits for declared dependencies, and compensates the successful ones when a later step fails. The caller makes one call; the ordering, mapping, and unwinding happen in the Engine.

Unified operations work in TypeScript or Python kind: sdk configs and in kind: mcp configs. Go SDK generation does not support them. MCP exposes each token-authorized authored name through search_docs and executes it through the existing execute tool.

They wrap operations already selected in services. They grant no new scope and carry no credentials.

The shape

unified_operations sits at the top level, beside services:

apiVersion: fused/v1
kind: sdk
name: issues
version: "1.0.0"
language: typescript
services:
  github: {operations: [createIssue, deleteIssue]}
  gitlab: {operations: [createIssue]}

unified_operations:
  issues.create:
    input:
      type: object
      required: [title]
      properties: {title: {type: string}}
    bindings:
      github:
        operation: createIssue
        input: {title: "${input.title}"}
        rollback: {operation: deleteIssue, input: {id: "${response.github.id}"}}
      gitlab: createIssue

For MCP, use kind: mcp, omit language, and keep the same unified_operations block. In an SDK, dot-separated names become the generated namespace: issues.create produces sdk.unified.issues.create. MCP preserves issues.create as the exact operation name returned by search_docs and accepted by execute.

Operation properties

Property	Required	What it does
`input`	Yes	JSON Schema for the logical operation’s public input
`bindings`	Yes	Map of step names to selected provider operations; max 16
`output`	No	Final projection. Its constructed object becomes the exact return value
`description`	No	Metadata retained with the immutable definition

An SDK or MCP app version may declare at most 64 unified operations.

Binding properties

A binding is either a bare operation ID or an expanded object.

bindings:
  gitlab: createIssue          # compact: step key also selects the service
  github:                      # expanded
    service: github
    operation: createIssue
    input: {title: "${input.title}"}
    depends_on: [gitlab]
    rollback:
      operation: deleteIssue
      input: {id: "${response.github.id}"}

Property	What it does
`service`	The configured service key. Omitted, it defaults to the binding key
`operation`	Exact case-sensitive `operationId`, already selected for that service
`input`	Maps unified input and direct dependency responses into the provider request
`depends_on`	Makes this step wait for the named steps
`rollback.operation`	An operation on the same service that compensates this one
`output`	Optional projection for this step’s result

Each binding key is a unique step name used by depends_on, response references, caller targets, and the returned result.target. It does not have to match a service key — several steps may use one service, and they stay separate steps with separate results. Quote a provider-qualified service that starts with @, like "@acme/github".

How execution runs

Steps run as their dependencies settle, several at a time. Once every forward call has finished, rollback runs in reverse dependency order. A failed step compensates only its successful direct dependencies that declare rollback.

An output-mapping error happens after the provider call succeeded, so it neither triggers rollback nor blocks dependants.

depends_on values must be exact binding keys — self-dependencies, duplicates, unknown targets and cycles are all rejected. There is no on_failure; application code owns fallback.

Mapping values

Values in bindings.<step>.input, rollback.input, and output projections can reference the operation’s input and earlier responses. Operation-level input is plain JSON Schema. A complete reference keeps its JSON type — `${response.drive.files}` stays an array — while a reference mixed into a string interpolates. Two operators are available: ?? takes the first non-null value, and a trailing ? omits a missing one. What each location may read:

Location	Can reference
`bindings.<step>.input`	`input.`, `target`, and `response.<direct-dependency>.`
`rollback.input`	`input.`, `target`, and that step’s own `response.<step>.`
Operation `output`	`input.` and `response.<declared-target>.` after bindings settle
Binding `output`	`input.`, `target`, and that binding’s raw `response.<step>.`

Shaping the return value

Without output, the call returns the all-settled {results, rollbacks} envelope. With it, your constructed object is the return value — no data wrapper, no envelope.

    output:
      type: object
      required: [primary_id, title, provider_ids]
      properties:
        primary_id: "${response.github.id}"
        title: "${response.github.issue.title}"
        provider_ids:
          type: array
          value: ["${response.github.id}", "${response.gitlab.iid}"]
          items: {type: string}

Binding outputs run first and become the response values the operation output reads. Scalar shorthand infers its type from the authored JSON scalar; expanded scalars use {type, value}. Arrays take one value plus optional schema-only items. The {schema, mapping} form is invalid — use only the recursive output tree.

Validate before you apply

# SDK
fused-cli sdk validate -f .fused/sdks/issues.yaml --json
fused-cli sdk plan -f .fused/sdks/issues.yaml --json

# MCP
fused-cli mcp validate -f .fused/mcps/issues.yaml --json
fused-cli mcp plan -f .fused/mcps/issues.yaml --json

Unified operations live inside an immutable SDK or MCP app version like everything else. Changing one under an existing version returns app_version_immutable — publish a new version.

Call a unified operation

Targets, selectors, and reading the results envelope.

Get Started

Guides

Reference

Declare a unified operation

The shape

Operation properties

Binding properties

How execution runs

Mapping values

Shaping the return value

Validate before you apply

Call a unified operation

​The shape

​Operation properties

​Binding properties

​How execution runs

​Mapping values

​Shaping the return value

​Validate before you apply

Call a unified operation

The shape

Operation properties

Binding properties

How execution runs

Mapping values

Shaping the return value

Validate before you apply