Using Flowyn from coding agents

How ChatGPT, Claude Code, Cursor, and other coding agents can discover and integrate Flowyn through REST, the OpenAPI document, llms.txt, and the repository SDK, CLI, and stdio MCP server.

Can a coding agent integrate Flowyn?

Yes. Flowyn is plain REST with JSON resources. An agent can read llms.txt for a summary, llms-full.txt for every docs page as text, and the OpenAPI document for exact contracts.

What an agent should know

Authenticate with Authorization: Bearer and keep the key server-side.
Send Idempotency-Key on creates.
Asynchronous creates return HTTP 202 with an id. Read the resource for status.
Delivery and execution are at-least-once. Deduplicate in receivers.
Flowyn records and reports. It does not operate the caller's systems or run their agents.

A prompt you can paste

text

Integrate Flowyn (https://flowyn.dev). Read https://flowyn.dev/llms.txt and the OpenAPI document at https://api.flowyn.dev/openapi/v1.yaml.
Use the REST API at https://api.flowyn.dev with Authorization: Bearer $FLOWYN_API_KEY from the server environment.
Send an Idempotency-Key header on creates, keep the returned id, and read status with GET.
Task: <describe the operation, e.g. "send order.completed events to https://hooks.example.com/orders">.

Instrumenting an agent you built

If the agent you are building should report to Flowyn, start with the agent overview. Use REST or the repository Node SDK resources agents, agentRuns, telemetry, approvals, and providerConnections. Approval decisions remain available only through a human session.

SDK, CLI, and MCP

A Node SDK, a CLI, and a stdio MCP server live in the Flowyn repository. The Node SDK wraps existing Agent APIs. MCP also provides read-only Agent identity, run, trace, usage, and approval inspection. Use SDK or REST for other Agent operations; the CLI retains its existing primitive commands. These packages are not published to a registry and the MCP server is not hosted.

Build from source

From the Flowyn repository root, use Node >= 22.13 and pnpm 11.21.0:

bash

pnpm install --frozen-lockfile
pnpm --filter @flowyn/cli build
# Set FLOWYN_API_KEY securely in your server environment first.
pnpm flowyn context
pnpm flowyn --help

Stdio MCP configuration

Configure your coding client to launch Node with the absolute path to packages/cli/dist/index.js, arguments mcp --preset read, and a server-side Development key. Set FLOWYN_BASE_URL only when using a different API deployment. Stdio is the connection; there is no hosted MCP URL. Read tools are the default. --preset operate enables creates and retries while omitting deletion and secret rotation; cancellation requires confirm_resource_name equal to the resource id; --write enables the full existing mutation set with explicit destructive confirmation. Production writes also require --allow-live.

Codex

Add this to ~/.codex/config.toml. Set FLOWYN_API_KEY securely in the environment that launches Codex; env_vars passes the named variable to the server without storing its value in the configuration. Verify with codex mcp list. See the Codex MCP reference.

toml

[mcp_servers.flowyn]
command = "node"
args = ["/absolute/path/to/flowyn/packages/cli/dist/index.js", "mcp", "--preset", "read"]
env_vars = ["FLOWYN_API_KEY"]

Claude Code and Cursor

Claude Code uses project .mcp.json. Cursor uses project .cursor/mcp.json or user ~/.cursor/mcp.json. Store your flw_test_ key in a mode-600 file outside the repository. This configuration supplies only the absolute path; Flowyn reads the key file when the client launches the server.

Claude Code / Cursor configuration

{
  "mcpServers": {
    "flowyn": {
      "command": "node",
      "args": [
        "/absolute/path/to/flowyn/packages/cli/dist/index.js",
        "mcp",
        "--preset",
        "read"
      ],
      "env": {
        "FLOWYN_API_KEY_FILE": "/absolute/path/outside/repository/flowyn-test-key"
      }
    }
  }
}

Discovery

Call session_context, then discover_capabilities. The catalogue covers all five primitives and Agent infrastructure. Use REST when a capability has no SDK, CLI, or MCP name; do not invent a tool from a route.

Inspect an Agent

Use agents_list and agents_get to resolve an identity, then agent_runs_list and agent_runs_get to find its reported runs. Pass a returned run id to agent_traces_list, then its trace_id to agent_traces_get. Trace steps are concurrent metadata, retained 30 days; a truncated trace is incomplete evidence. agent_usage with agent_id and last: "24h" reads advisory warnings, which never enforce a budget or restrict execution. Use agent_approvals_list with status: "pending" and agent_approvals_get to explain the action a signed-in human must decide. MCP cannot decide, pause, resume, signal, or cancel an Agent.

Uncertain writes

The SDK reuses an idempotency key within its retries. A final FlowynError preserves it as idempotencyKey. Retry the same body with { idempotencyKey: error.idempotencyKey }; a new SDK call without that option would create a new key. Preserve next, retryAfterSeconds, and request/error ids when handling errors. The canonical reference is https://flowyn.dev/docs/getting-started/errors.

Next step

Limits and credits.