Workflows MCP

Run YAML workflows as MCP tools so agents can automate real tasks with one server.

Why this project

workflows-mcp gives MCP clients a reusable automation layer:

• Define tasks once in YAML and run them from any MCP-compatible client.

• Orchestrate multi-step work with dependency-aware execution.

• Support interactive runs (Prompt blocks) with pause/resume.

• Keep secrets server-side via WORKFLOW_SECRET_* with redacted outputs.

• Run synchronous or async jobs with queue visibility and cancellation.

Quickstart (5 minutes)

1) Install

Requires Python 3.12+.

uv pip install workflows-mcp

or:

pip install workflows-mcp

2) Add to your MCP client

Example (claude_desktop_config.json):

{
  "mcpServers": {
    "workflows": {
      "command": "uvx",
      "args": ["workflows-mcp"],
      "env": {
        "WORKFLOWS_TEMPLATE_PATHS": "/path/to/your/workflows",
        "WORKFLOWS_LOG_LEVEL": "INFO",
        "WORKFLOW_SECRET_API_KEY": "your-secret-value"
      }
    }
  }
}

If installed with pip:

{
  "mcpServers": {
    "workflows": {
      "command": "workflows-mcp",
      "env": {
        "WORKFLOWS_TEMPLATE_PATHS": "/path/to/your/workflows",
        "WORKFLOWS_LOG_LEVEL": "INFO",
        "WORKFLOW_SECRET_API_KEY": "your-secret-value"
      }
    }
  }
}

3) Restart your MCP client and run first calls

1. list_workflows

2. get_workflow_info

3. execute_workflow

Instructions for LLM Agents

Use this call order for reliable results:

1. Discover: call list_workflows.

2. Inspect: call get_workflow_info for required inputs.

3. Execute: call execute_workflow.

4. Track async runs (if mode="async"): call get_job_status (or list_jobs).

5. Resume interactive workflows: call resume_workflow only for paused jobs (typically from Prompt blocks).

6. Reload definitions after YAML edits: call reload_workflows.

When authoring workflows, validate first:

• validate_workflow_yaml before execute_inline_workflow.

• Use get_workflow_schema for current schema details.

• Use the block reference for exact field names and required inputs: docs/llm/block-reference.md.

Async mini-flow example:

execute_workflow(workflow="python-ci-pipeline", inputs={...}, mode="async")
→ returns job_id
→ get_job_status(job_id="job_...") until completed/failed/paused
→ if paused, resume_workflow(job_id="job_...", response="...")

Available MCP tools (catalog + call patterns)

Workflow discovery and execution

Authoring and validation

Async, queue, and interactive control

Memory (conditional)

IMPORTANT: The memory tool is registered only when memory DB setup is available and valid at startup (see below)

Memory contract highlights:

• Unified envelope: operation + optional scope/query/record/graph/maintenance/response.

• Current memory taxonomy: scope accepts only palace, wing, room, compartment.

• Context activation and scope defaulting:

  • Resolution precedence is scope → scope_token → context_id (per-field merge).

  • scope_token resolves from execution context memory_scope_tokens; context_id resolves from memory_context_scopes.

  • Responses include resolved_scope and scope_source when available.

  • Required scope by operation:

    • query: all four fields must resolve.

    • ingest: all four fields must resolve (including compartment).

    • graph_upsert with graph.kind="place": all four fields must resolve.

    • validate|supersede|archive|maintain|graph_delete|graph_upsert(kind="link"): scope is optional.

• Temporal query semantics:

  • operation="query" supports either query.as_of OR interval query.from/query.to (mutually exclusive).

  • query.mode="graph" supports query.as_of only; query.from/query.to are rejected.

  • operation="ingest" with record.format="raw" supports record.valid_from and record.valid_to with ordering validation (valid_from <= valid_to).

• Strict validation: unknown/extra fields are rejected.

• Direct vs derived boundaries:

  • operation="ingest" is direct-only (record.memory_tier must be direct).

  • Category governance for ingest is explicit:

    • Unknown record.categories fail deterministically with MEM_UNKNOWN_CATEGORY when record.allow_create_categories=false (default behavior).

    • Setting record.allow_create_categories=true opts into category creation and allows ingest to proceed when categories are otherwise valid.

  • Derived/community artifacts are produced by maintenance flows (for example maintenance.mode="community_refresh").

  • query.mode="communities" uses the dedicated communities strategy.

• Lifecycle semantics:

  • Archived records are excluded by default query behavior.

  • operation="supersede" requires record.superseded_by.

  • operation="archive" maps to forget semantics; repeating archive on already archived records is safe/idempotent.

• Graph semantics:

  • operation="graph_upsert" with graph.kind="link" is idempotent.

  • operation="graph_delete" returns compact delete counters (deleted_places for kind="place", deleted_links for kind="link"); optional debug output adds diagnostics metadata.

Validation note: this ingest category behavior (MEM_UNKNOWN_CATEGORY with create disabled, successful ingest with allow_create_categories=true) was live-validated on 2026-04-21 via production-like direct MCP memory calls.

Direct-call JSON examples:

query:

{
  "operation": "query",
  "scope": {"palace": "acme", "wing": "workflows", "room": "memory-engine", "compartment": "contract-r2"},
  "query": {"mode": "search", "text": "schema epoch", "as_of": "2026-04-20T00:00:00Z", "radius": 1}
}

ingest:

{
  "operation": "ingest",
  "scope": {"palace": "acme", "wing": "workflows", "room": "memory-engine", "compartment": "contract-r2"},
  "record": {"format": "raw", "content": "Memory active", "memory_tier": "direct"}
}

validate:

{
  "operation": "validate",
  "record": {"ids": ["11111111-1111-1111-1111-111111111111"]}
}

supersede:

{
  "operation": "supersede",
  "record": {
    "ids": ["11111111-1111-1111-1111-111111111111"],
    "superseded_by": "22222222-2222-2222-2222-222222222222"
  }
}

archive:

{
  "operation": "archive",
  "record": {"ids": ["11111111-1111-1111-1111-111111111111"]}
}

maintain:

{
  "operation": "maintain",
  "maintenance": {"mode": "community_refresh"}
}

graph_upsert (kind=place):

{
  "operation": "graph_upsert",
  "scope": {"palace": "acme", "wing": "workflows", "room": "memory-engine", "compartment": "contract-r2"},
  "graph": {"kind": "place", "place_name": "Memory API (current)", "place_type": "feature"}
}

graph_upsert (kind=link):

{
  "operation": "graph_upsert",
  "graph": {
    "kind": "link",
    "from": "11111111-1111-1111-1111-111111111111",
    "to": "22222222-2222-2222-2222-222222222222",
    "link_type": "depends_on"
  }
}

graph_delete:

{
  "operation": "graph_delete",
  "graph": {"kind": "place", "ids": ["33333333-3333-3333-3333-333333333333"]}
}

project_onboard:

{
  "scope": {"palace": "acme", "wing": "workflows", "room": "memory-engine", "compartment": "contract-r2"},
  "ingest": {"format": "raw", "content": "Initial baseline", "memory_tier": "direct"},
  "supersede": {"ids": ["11111111-1111-1111-1111-111111111111"], "superseded_by": "22222222-2222-2222-2222-222222222222"},
  "archive": {"ids": ["33333333-3333-3333-3333-333333333333"]},
  "maintain": {"mode": "community_refresh"},
  "max_operations": 1
}

project_sync:

{
  "checkpoint": {
    "version": "oss-r2",
    "scope": {"palace": "acme", "wing": "workflows", "room": "memory-engine", "compartment": "contract-r2"},
    "plan": [{"operation": "ingest", "payload": {"format": "raw", "content": "Initial baseline", "memory_tier": "direct"}}],
    "next_index": 0,
    "completed": []
  },
  "max_operations": 3
}

Invalid (mutually exclusive temporal filters):

{
  "operation": "query",
  "scope": {"palace": "acme", "wing": "workflows", "room": "memory-engine", "compartment": "contract-r2"},
  "query": {
    "mode": "search",
    "text": "maintenance",
    "as_of": "2026-04-20T00:00:00Z",
    "from": "2026-04-01T00:00:00Z",
    "to": "2026-04-20T00:00:00Z"
  }
}

Invalid (graph query rejects interval filters):

{
  "operation": "query",
  "scope": {"palace": "acme", "wing": "workflows", "room": "memory-engine", "compartment": "contract-r2"},
  "query": {
    "mode": "graph",
    "text": "service graph",
    "from": "2026-04-01T00:00:00Z",
    "to": "2026-04-20T00:00:00Z"
  }
}

Invalid (legacy taxonomy key):

{
  "operation": "query",
  "scope": {"palace": "acme", "wing": "svc", "room": "component", "hall": "legacy"},
  "query": {"text": "find this", "mode": "search"}
}

Invalid (supersede missing required superseded_by):

{
  "operation": "supersede",
  "record": {
    "ids": ["11111111-1111-1111-1111-111111111111"]
  }
}

Configuration

Workflow loading and execution

• WORKFLOWS_TEMPLATE_PATHS: Comma-separated workflow directories to load.

• WORKFLOWS_MAX_RECURSION_DEPTH: Max workflow composition depth (default: 50).

• WORKFLOWS_LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL; default: INFO).

Queue and async settings

• WORKFLOWS_IO_QUEUE_ENABLED: Enable serialized I/O queue (default: true).

• WORKFLOWS_JOB_QUEUE_ENABLED: Enable async job queue (default: true).

• WORKFLOWS_JOB_QUEUE_WORKERS: Queue workers (default: 3).

• WORKFLOWS_MAX_CONCURRENT_JOBS: Max active + queued jobs (default: 500).

• WORKFLOWS_JOB_TIMEOUT: Default async timeout in seconds (default: 3600).

• WORKFLOWS_JOB_HISTORY_MAX: Max retained job records (default: 1000).

• WORKFLOWS_JOB_HISTORY_TTL: Job retention TTL in seconds (default: 86400).

Secrets and LLM config

• WORKFLOW_SECRET_<NAME>: Secret value exposed as {{secrets.NAME}}.

• WORKFLOWS_LLM_CONFIG: Optional path override for LLM config.

Memory

Memory is an optional persistent storage feature that lets agents and workflows record, retrieve, and organize information across sessions. It is backed by PostgreSQL and gives each agent a structured, scoped, and temporally-aware knowledge store.

What memory provides

• memory MCP tool — direct call interface for LLM agents to store and query information without writing workflow YAML.

• project_onboard / project_sync MCP tools — Current memory contract helpers for checkpointed onboarding/sync sequences.

• Memory workflow block — use inside YAML workflows to automate memory operations as part of larger pipelines.

• Memory topology scoping (palace → wing → room → compartment) — current memory scope keys are strict and legacy keys (for example hall) are rejected. Scope can be supplied directly and/or resolved from context (scope_token, context_id) using deterministic precedence.

• Temporal tracking — records carry valid_from / valid_to timestamps supporting point-in-time and interval queries.

• Knowledge graph — link memories to places, entities, or concepts and query the resulting graph.

• Lifecycle management — archive or supersede records without deletion; archived records are excluded from default queries.

Retrieval strategies

Current memory behavior exposes query modes that map to retrieval strategies internally:

Every query call still requires a fully resolved current memory scope (palace/wing/room/compartment) resolved from request and/or context sources.

Scope call shape (with context activation)

Scope fields can be passed directly and/or resolved from scope_token / context_id:

{
  "operation": "query",
  "scope": {"palace": "acme", "wing": "my-service"},
  "scope_token": "st_auth",
  "context_id": "ctx_default",
  "query": {"text": "refresh token lifetime", "mode": "context"}
}

Resolution precedence is scope → scope_token → context_id for each field.

Prerequisites

• PostgreSQL 13 or later, network-accessible from the server process.

• A database user with CREATE DATABASE rights on the admin database (typically postgres) if auto-create is enabled, or a pre-existing database that the user can connect to.

Configuration

Enabling memory

Add the following variables to your MCP client config:

{
  "mcpServers": {
    "workflows": {
      "command": "uvx",
      "args": ["workflows-mcp"],
      "env": {
        "MEMORY_DB_HOST": "localhost",
        "MEMORY_DB_PORT": "5432",
        "MEMORY_DB_NAME": "memory_db",
        "MEMORY_DB_USER": "postgres",
        "MEMORY_DB_PASSWORD": "your-password"
      }
    }
  }
}

On first boot with MEMORY_DB_AUTO_CREATE=true (the default), the server creates the target database and applies the schema automatically. Restart your MCP client after adding the variables.

Verifying memory is active

1. Restart your MCP client.

2. Call list_workflows — confirm the server started without errors in the client logs.

3. Check that the memory tool appears in the available tool list.

4. Run a test ingest:

{
  "operation": "ingest",
  "scope": {"palace": "acme", "wing": "test", "room": "setup", "compartment": "smoke"},
  "record": {"format": "raw", "content": "Memory is working.", "memory_tier": "direct"}
}

If the tool is absent, check server logs for MEMORY_DB_* startup errors — the most common causes are an unreachable host, incorrect credentials, or a schema epoch mismatch.

Schema compatibility

Memory schema versions are tracked by epoch. If the epoch in the database does not match the server version:

• Startup fails with an explicit error.

• Apply the documented migration and restart.

• No automatic destructive reset is performed. Set MEMORY_SCHEMA_RESET_MODE only if you intend a one-time destructive reset on a non-production instance.

Workflows for users

Use registered workflows for repeatable automation, and inline workflows for experiments.

• Registered workflows: best for shared, reusable operations.

• Inline workflows: best for quick tests and prototyping.

Author workflow YAML with exact block input names from:

• docs/llm/block-reference.md

Example block families include Shell, ReadFiles, HttpCall, LLMCall, Sql, Workflow, Prompt, and Memory.

Documentation map

• README.md: install, usage, and tool catalog.

• docs/guides/memory-tools-cheatsheet.md: Current memory contract quick reference, detailed guide, and examples.

• docs/llm/block-reference.md: exact block inputs/outputs for workflow authoring.

• docs/TESTING.md: test strategy and test commands.

• ARCHITECTURE.md: architecture overview.

• docs/adr/: design decisions and rationale.

• CHANGELOG.md: release history.

Contributing

1. Fork the repository and create a focused branch.

2. Add or update tests with your change.

3. Run quality checks before opening a PR:

uv run pytest
uv run ruff check src/workflows_mcp/
uv run mypy src/workflows_mcp/

4. Describe behavior changes and config impact clearly in the PR.

Support and community

• Issues and bug reports: https://github.com/qtsone/workflows-mcp/issues

• Project repository: https://github.com/qtsone/workflows-mcp

License

AGPL-3.0-or-later. See LICENSE.