For coding agents

Chatterfly is built so coding agents can author workflows reliably. Workflows are a JSON DSL with a published schema, a validation endpoint with no side effects, and machine-readable reference docs an agent can load on demand.

Overview

There are three entry points an agent can use, in increasing order of integration:

Surface	Use it for
llms.txt	Zero-setup discovery — a single text file linking the DSL reference, schema, and validation endpoint.
AGENTS.md	Repo-level instructions when the workflow JSON lives in your codebase.
MCP server	Full tool access — validate, create, update, deploy, and trigger workflows from inside the agent.

llms.txt & DSL reference

Every Chatterfly deployment serves an llms.txt discovery file plus the full DSL reference as plain Markdown. All URLs are derived from your app origin.

bash

$APP_URL/llms.txt                 # discovery entry point
$APP_URL/llms/dsl-core.md         # execution model, state, IDs
$APP_URL/llms/dsl-nodes.md        # node table + field specs
$APP_URL/llms/dsl-conditions.md   # condition expression syntax
$APP_URL/llms/dsl-input-fields.md # input_type variants
$APP_URL/llms/dsl-hitl.md         # human-in-the-loop model
$APP_URL/schemas/workflow.json    # JSON schema
$APP_URL/openapi.yaml             # management API spec

Tip: Point your agent at $APP_URL/llms.txt first — it links everything else.

AGENTS.md

When workflow definitions live in your repository, drop an AGENTS.md at the root so agents pick up the authoring rules automatically: load the DSL reference, never set dsl_version manually, use PascalCase node types, keep sibling IDs unique, and always validate before deploy.

MCP server

The backend can expose a Model Context Protocol server over streamable HTTP at /mcp. It is disabled by default — set MCP_ENABLED=true on the backend to enable it.

The tools are thin clients over the management API, so they inherit the same auth: pass your management bearer token (and X-Tenant-ID for a non-default tenant) in the MCP request.

json

{
  "mcpServers": {
    "chatterfly": {
      "url": "${PUBLIC_API_URL}/mcp",
      "headers": {
        "Authorization": "Bearer ${CHATTERFLY_TOKEN}"
      }
    }
  }
}

Available tools:

Tool	Description
validate_workflow	Validate a DSL definition.
create_workflow	Create a workflow.
update_workflow	Update a workflow.
deploy_workflow	Deploy a workflow.
trigger_workflow	Trigger a test run.
get_run	Fetch a run by ID.
list_connections	List configured connections.
list_tools	List tools available to Agent nodes.
get_dsl_reference	Load a DSL reference section.

Validation endpoint

The validation endpoint has no side effects — agents can call it as often as needed while iterating. It runs the same engine validators as the save path plus a DSL-version gate.

bash

curl -X POST "$CHATTERFLY_API_URL/api/management/workflows/validate" \
  -H "Authorization: Bearer $CHATTERFLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "definition": { /* workflow JSON */ } }'

The response shape is { valid, dsl_version, errors[], warnings[] }, where each issue carries { path, code, message, severity }.