> ## Documentation Index
> Fetch the complete documentation index at: https://flow.engineer/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Your first Flow project

> Create a project, choose an interface and make your first tool call.

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

**1. Create the starter**

Run this from the folder where you keep your projects:

```sh 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`:
>
> ```sh Terminal
> npx @flow-engineer/flow init --display-name "My agent"
> npm install
> ```

**2. Choose how to try it**

**MCP & CLI**

Start the MCP server:

```sh 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:

```sh 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.
>
> ```json
> {
>   "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](https://flow.engineer/docs/framework/mcp.md).

**Messaging**

Connect a trial channel, then run the agent:

```sh 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:

```text 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](https://flow.engineer/docs/reference.md#models) for provider selection and defaults.

> [!NOTE]
>
> 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](https://flow.engineer/docs/agents.md#shared-test-numbers-and-privacy)

**3. 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:

```sh 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:
>
> ```sh 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](https://flow.engineer/docs/build-agent.md)**
>
> Implement a capability and call it from the CLI.

> **[Explore the playground](https://flow.engineer/docs/playground.md)**
>
> Inspect tool calls, switch channels and test sign-in.