AI Assistant Integration¶

Overview¶

Floh is designed to work with AI assistants through:

OIDC access tokens whose scope claim carries the caller's permissions
AI-friendly API endpoints for validation, diagnosis, and documentation
An MCP (Model Context Protocol) server for structured tool access (planned)

For product strategy, runtime use cases, guardrails, and MVP patterns for LLMs inside Floh workflow design and execution, see AI Agents in Floh Workflows.

Quick Start¶

Obtain an OIDC access token from Authifi — see MCP Setup
Configure your AI assistant with the refresh token so it can mint access tokens
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 <access-token>" \
  -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¶

AI actions are attributed to the authenticated user carried by the access token's sub claim, exactly like a browser-initiated action.

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

Obtain an OIDC refresh token for your user — see MCP Setup § Obtain a Refresh Token. The permissions your AI can exercise are whatever scope Authifi issues for you; grant them by adding your user to the appropriate Authifi groups rather than by minting a Floh-side token.
Configure environment variables:

export FLOH_API_URL=https://localhost:7070   # Floh API base URL (preferred; use http:// only for HTTP-only dev)
export OIDC_ISSUER=https://a-ci.ncats.io/_api/auth/ls
export OIDC_CLIENT_ID=floh-mcp-client
export OIDC_CLIENT_SECRET=<mcp-client-secret>   # client_secret_post; from env/mcp.env
export FLOH_MCP_AUDIENCE=http://mcp.floh.api
export FLOH_REFRESH_TOKEN=<your-refresh-token>

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": "https://localhost:7070",
        "OIDC_ISSUER": "https://a-ci.ncats.io/_api/auth/ls",
        "OIDC_CLIENT_ID": "floh-mcp-client",
        "OIDC_CLIENT_SECRET": "<mcp-client-secret>",
        "FLOH_MCP_AUDIENCE": "http://mcp.floh.api",
        "FLOH_REFRESH_TOKEN": "<your-refresh-token>"
      }
    }
  }
}

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`