AI Assistant Integration¶

Overview¶

Floh is designed to work with AI assistants through:

Scoped API tokens for secure, delegated access
AI-friendly API endpoints for validation, diagnosis, and documentation
An MCP (Model Context Protocol) server for structured tool access (planned)

Quick Start¶

Create an API token — see API Tokens
Configure your AI assistant with the token
Start using the API endpoints below

Workflow Authoring Endpoints¶

POST /api/workflows/validate¶

Validate a workflow definition without saving. Returns structured errors, warnings, and subject variable validation. Supports strict: true for publish-time rules.

Example:

curl -X POST https://floh.example.com/api/workflows/validate \
  -H "Authorization: Bearer floh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Workflow",
    "steps": [...],
    "trigger": { "types": ["manual"] },
    "variables": [],
    "onError": "stop",
    "strict": true
  }'

Response:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "subjectVariableError": null
}

Failure Analysis¶

GET /api/runs/:id/diagnose¶

Returns comprehensive run diagnosis:

Run metadata and status
Workflow definition context
All step statuses and errors
Failed step details with configuration
Audit trail
Suggested next actions (retry, skip, fix workflow)

Documentation Generation¶

GET /api/workflows/:id/docs¶

Generates markdown documentation:

Overview table (status, version, category, trigger, error strategy)
Variable reference table
Step-by-step table with transitions
ASCII flow diagram
Step detail sections with configuration
API example for starting runs

Workflow CRUD API¶

Method	Endpoint	Permission	Description
POST	/api/workflows	workflow:create	Create draft
PUT	/api/workflows/:id	workflow:update	Update draft
POST	/api/workflows/validate	workflow:read	Dry-run validation
POST	/api/workflows/:id/publish	workflow:publish	Publish to active
POST	/api/workflows/:id/start	workflow:start	Start a run
GET	/api/workflows/:id/docs	workflow:read	Generate docs
POST	/api/workflows/:id/create-version	workflow:create	New draft from active

Run Management API¶

Method	Endpoint	Permission	Description
GET	/api/runs	run:read	List runs
GET	/api/runs/:id	run:read	Get run details
GET	/api/runs/:id/diagnose	run:read	Failure analysis
POST	/api/runs/:id/retry	run:update	Retry failed run
POST	/api/runs/:id/cancel	run:cancel	Cancel run

Context Discovery¶

List available system resources:

Endpoint	Purpose
GET /api/connectors	Available connectors for connector steps
GET /api/roles	Role definitions for role_grant/revoke steps
GET /api/projects	Projects and workflow sets
GET /api/users	Users for assignee/approver references
GET /api/groups	User groups
GET /api/schedules	Scheduled triggers

Typical AI Workflow¶

Steps an AI follows to create a workflow:

Discover resources (connectors, roles, projects)
Construct workflow JSON
Validate with POST /api/workflows/validate
Create draft with POST /api/workflows
Publish with POST /api/workflows/:id/publish
Generate docs with GET /api/workflows/:id/docs

Typical AI Diagnosis Flow¶

List failed runs: GET /api/runs?status=failed
Diagnose: GET /api/runs/:id/diagnose
Recommend action based on diagnosis
Optionally retry or skip

Audit Trail¶

All AI actions via API tokens include metadata:

{ "via": "api_token", "tokenName": "Cursor MCP", "tokenPrefix": "floh_a1b2" }

Filter audit logs: GET /api/audit-logs?actor=<userId>

MCP Server¶

Floh includes a Model Context Protocol (MCP) server that wraps all of the above endpoints into structured tools, resources, and prompts for AI assistants.

Setup¶

Install the MCP package dependencies (from the repo root):

pnpm install --filter @floh/mcp

Create an API token with the permissions your AI needs:

curl -X POST https://floh.example.com/api/auth/tokens \
  -H "Authorization: Bearer <your-session-cookie-or-token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Cursor MCP", "permissions": ["workflow:read","workflow:create","workflow:update","workflow:publish","workflow:start","run:read","run:update","run:cancel","connector:read","project:read","role_definition:read","user:read","group:read","schedule:read","config:export"] }'

Configure environment variables:

export FLOH_API_URL=http://localhost:3000   # your Floh API base URL
export FLOH_API_TOKEN=floh_...              # the token from step 2

Running Standalone¶

cd packages/mcp
pnpm dev          # development (tsx, auto-reload)
pnpm build && pnpm start   # production

Cursor Integration¶

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "floh": {
      "command": "npx",
      "args": ["tsx", "packages/mcp/src/index.ts"],
      "env": {
        "FLOH_API_URL": "http://localhost:3000",
        "FLOH_API_TOKEN": "floh_..."
      }
    }
  }
}

Available Tools¶

Tool	Description	Permission
`list_workflows`	List workflow definitions with filters	workflow:read
`get_workflow`	Get full workflow definition	workflow:read
`create_workflow`	Create a new draft workflow	workflow:create
`update_workflow`	Update an existing draft	workflow:update
`validate_workflow`	Dry-run validation	workflow:read
`publish_workflow`	Publish draft to active	workflow:publish
`create_version`	New draft from active workflow	workflow:create
`generate_workflow_docs`	Generate markdown docs	workflow:read
`list_runs`	List workflow runs with filters	run:read
`get_run`	Get run details with step statuses	run:read
`start_run`	Start a new workflow run	workflow:start
`cancel_run`	Cancel a running workflow	run:cancel
`retry_run`	Retry a failed run	run:update
`diagnose_run`	Comprehensive failure analysis	run:read
`list_connectors`	List available connectors	connector:read
`list_projects`	List projects and workflow sets	project:read
`list_roles`	List role definitions	role_definition:read
`list_users`	List system users	user:read
`list_groups`	List user groups	group:read
`list_schedules`	List scheduled triggers	schedule:read
`export_config`	Export configuration as JSON	config:export
`import_config`	Import configuration from JSON	config:import

Available Resources¶

URI	Content
`floh://schema/workflow-definition`	Full workflow definition schema
`floh://schema/step-types`	All step types with config schemas
`floh://examples/simple-approval`	Simple approval workflow example
`floh://examples/provisioning`	Access provisioning workflow example
`floh://reference/condition-syntax`	Condition expression syntax guide
`floh://reference/variable-interpolation`	Variable interpolation syntax guide

Available Prompts¶

Prompt	Description	Arguments
`create-workflow`	Guided workflow creation from natural language	`description`, `category?`
`diagnose-failure`	Guided failure diagnosis for a run	`runId`
`document-workflow`	Generate comprehensive workflow documentation	`workflowId`