Your first Flow project

Start with the café example and try its MCP server, CLI or messaging agent. All three use the same tools.

Before you start

You need Node.js 22.18 or later and npm. Check your version with node --version.

MCP and CLI tool calls run without a model key or Flow account. The messaging agent needs a model; you can use your own provider key or Flow’s trial setup.

Create your project

Create the starter

Run this from the folder where you keep your projects:

Terminal

npx @flow-engineer/flow new my-agent --display-name "My agent"
cd my-agent
npm install

Use lowercase letters, digits and dashes for the folder name. --display-name is what people call your agent.

Already in an empty project folder?

Use init instead of new:

Terminal

npx @flow-engineer/flow init --display-name "My agent"
npm install

Choose how to try it

MCP & CLI

Start the MCP server:

First terminal

npm run mcp

It prints its MCP URL and a command to connect Claude Code. Keep it running. In another terminal in the same project, read the café menu:

Second terminal

npm run cli -- menu --json

Check it worked: you should see JSON with a menu array, including the café’s drinks, prices, milk options and allergens.

See the shape of the result

This is an excerpt; the starter returns the full menu.

{
  "menu": [
    {
      "item": "Latte",
      "sizes": { "small": 4, "large": 4.8 },
      "milks": ["whole", "oat", "almond"],
      "allergens": ["dairy (unless plant milk)"]
    }
  ],
  "note": "This is the whole menu."
}

To try the same tools in an assistant, connect the MCP URL using the command printed by the server. Remote hosts such as Claude or ChatGPT need a public HTTPS endpoint: see MCP servers.

Messaging

Connect a trial channel, then run the agent:

Terminal

npx @flow-engineer/flow link --channel telegram
npm start

link opens sign-in, sets up the keys in .env and prints a phone link. You can choose --channel whatsapp or --channel imessage when those channels are available.

Open the playground URL from npm start. Pick a test person and send:

Try this

What's on the menu?

Check it worked: the agent calls get_menu and replies with items from the café. Turn on Debug to see the tool call. Then open the phone link while npm start runs and try the same request from your phone.

Use your own model key

Set OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY or GEMINI_API_KEY in .env. A provider key with a value takes priority over FLOW_KEY. For a local-only playground, no messaging connection is required.

See models and configuration for provider selection and defaults.

Trial numbers are shared and intended for test data. A join code routes your phone to your app; sending another app’s code moves it. Connect your own number before using real customer data. Trial details

Make it your product

Add your own tools in src/tools.ts, write workflows in agent/skills/ and replace the café’s instructions in agent/AGENTS.md. The starter also includes coding-agent skills in .claude/skills/.

Check the tool and CLI definitions:

Terminal

npx @flow-engineer/flow check

Check it worked: the command reports no configuration problems. Then exercise a real request in the interface you chose.

Where to edit

File	What it owns
src/tools.ts	Product operations and their inputs, results and sign-in requirements
agent/skills/<name>/SKILL.md	Workflows around those operations
src/mcp.ts	MCP server and authentication
src/cli.ts	CLI names, command groups, arguments and output
src/agent.ts	Messaging agent, model and host options
agent/AGENTS.md	The messaging agent’s purpose and behavior

If something does not connect

The MCP server chose another port

The starter uses MCP_PORT, else port 8790 or the next free port. Use the URL it prints. For this my-agent project, set MY_AGENT_SERVER to that URL when running the CLI:

Terminal

MY_AGENT_SERVER=http://127.0.0.1:8791/mcp npm run cli -- menu --json

Replace 8791 with the actual port. The variable name is derived from the project name.

The messaging agent says no model key is set

Run npx @flow-engineer/flow link for Flow’s trial setup, or add your provider key to .env. Restart npm start after changing environment values.

The phone link works but the agent does not answer

Keep npm start running and restart it after link writes keys or a channel sender. WhatsApp and iMessage trial channels reply after you write first. Run npx @flow-engineer/flow status to see what the folder has and what is missing.

Add your first tool

Implement a capability and call it from the CLI.

Explore the playground

Inspect tool calls, switch channels and test sign-in.