Creating Custom Workflows
Learn how to build your own workflows, package them as MCP servers, and share with your team.
📚 In This Guide
Workflow Anatomy
Every Hydra workflow is defined in YAML with these core components:
name: workflow_name # Unique identifier
version: 1.0.0 # Semantic versioning
description: What this does # Clear description
inputs: # Optional inputs
- name: input_param
type: string
required: true
steps: # Workflow steps (required)
- name: step_1
tool: service.action
args:
param: value
- name: step_2
agent: ai_assistant
input: "${step_1.output}"
outputs: # Optional outputs
- name: result
value: "${step_2.output}"
Creating Your First Workflow
Let's create a simple deployment workflow step by step.
Step 1: Define the Workflow
Create a new file called deploy-staging.yaml:
name: deploy_to_staging
version: 1.0.0
description: Deploy branch to staging environment
steps:
# Step 1: Run all tests
- name: run_tests
tool: pytest
args:
- "--all"
- "--coverage"
# Step 2: Build Docker image
- name: build_image
tool: docker.build
args:
tag: "staging-${git.branch}"
context: "."
# Step 3: Deploy to Kubernetes
- name: deploy_k8s
tool: k8s.apply
args:
namespace: staging
image: "${build_image.output.tag}"
# Step 4: Run smoke tests
- name: smoke_tests
tool: pytest
args:
- "tests/smoke/"
- "--env=staging"
outputs:
- name: deployment_url
value: "${deploy_k8s.output.url}"
- name: deployment_status
value: "${smoke_tests.output.status}"
Step 2: Test Locally
Before deploying, test your workflow locally:
hydra test deploy-staging.yaml
✅ Workflow validated successfully
All steps are properly defined and dependencies are resolved.
Step Types
Hydra supports different types of steps for various use cases:
1. Tool Calls
Execute MCP tools (CLI commands, API calls, etc.):
- name: run_linter
tool: eslint
args:
- "src/"
- "--fix"
2. Agent Tasks
Use AI agents for complex reasoning:
- name: analyze_code
agent: code_analyzer
input: "Review this code for security issues"
context: "${file_contents}"
3. Conditional Steps
Execute steps based on conditions:
- name: deploy_production
tool: k8s.apply
condition: "${run_tests.output.success} == true"
args:
namespace: production
4. Parallel Steps
Run multiple steps concurrently:
- name: parallel_tests
parallel:
- name: unit_tests
tool: pytest
args: ["tests/unit/"]
- name: integration_tests
tool: pytest
args: ["tests/integration/"]
- name: e2e_tests
tool: playwright
args: ["tests/e2e/"]
Deploying as MCP Server
Once your workflow is ready, deploy it as an MCP server using FastMCP:
Option 1: FastMCP Cloud (Recommended)
fastmcp deploy deploy-staging.yaml
🚀 Deployed Successfully!
MCP URL: https://yourname-workflows.fastmcp.app/mcp
Workflow: deploy_to_staging v1.0.0
Option 2: Self-Hosted
fastmcp serve deploy-staging.yaml --port 8080
Sharing with Your Team
After deploying, share your workflow MCP URL with your team:
Share via URL
Team members can add your workflows to their IDE:
claude mcp add https://yourname-workflows.fastmcp.app/mcp
Share via GitHub
Commit your workflow YAML to a shared repository:
team-workflows/
├── workflows/
│ ├── deploy-staging.yaml
│ ├── deploy-production.yaml
│ └── run-tests.yaml
└── README.md
Team members can clone and deploy any workflow they need!
Advanced Topics
Variables & Templating
Use variables to make workflows reusable:
name: deploy_workflow
inputs:
- name: environment
type: string
required: true
- name: branch
type: string
default: "main"
steps:
- name: deploy
tool: k8s.apply
args:
namespace: "${environment}"
image: "app:${branch}"
Error Handling
Handle failures gracefully with retry and fallback:
- name: api_call
tool: http.post
retry:
max_attempts: 3
backoff: exponential
on_error:
- name: send_alert
tool: slack.send
args:
channel: "#alerts"
message: "API call failed: ${error.message}"
Secrets Management
Use environment variables for sensitive data:
- name: deploy
tool: k8s.apply
args:
namespace: production
secrets:
api_key: "${env.API_KEY}"
db_password: "${env.DB_PASSWORD}"
🔒 Security Note
Never commit secrets to your workflow YAML. Always use environment variables or secret management tools.