# Author flows with AI via an MCP server

> Connect MCP-capable AI assistants to NOVA Flow to build, validate, and save flows on a cell. Learn how to connect from Claude Code or GitHub Copilot, build your first flow, and create a custom node when none fits.

NOVA Flow exposes an MCP (Model Context Protocol) endpoint that an MCP-capable AI assistant can connect to.
As the action catalog, authoring rules, and validation are delivered by NOVA Flow itself, the assistant always has
the correct information matching the cell it is connected to, and allows for custom node to be built.

This means that flows written with the MCP server are always valid and no invalid flows are saved.

## Requirements

NOVA Flow v2026.9.13 or later is required for MCP support.

## Endpoint

NOVA Flow serves the endpoint at this path:

```
http://<instance-ip>/cell/controlplane/api/v1/mcp
```

1. Replace `<instance-ip>` with your NOVA OS instance's IP address.
2. Open the URL in a browser.
   → The response `{"detail":"Method Not Allowed"}` is displayed. This means the endpoint is available.
   > **Info:** The endpoint only answers `POST`requests.

## Tools

| Tool | Purpose |
| - | - |
| `list_node_types` | Cell's action catalog, including custom nodes |
| `get_tree_schema` | Behavior-tree JSON schema |
| `validate_tree` | Registry-aware validation (schema, actions, globals) |
| `list_trees` / `get_tree` | List and read stored flows |
| `save_tree` | Persist a flow (fail-closed) |
| `list_globals` | Available global keys |
| `get_node_authoring_guide` | Recipe for building a custom node |

## Connect Claude Code

> **Info:** `--transport http` is required. Without it, the MCP server you're about to create is registered as a
> broken stdio server.

**NOVA Cloud instance**

1. Open your instance.
2. Add the server to your user scope:

```bash
claude mcp add --scope user --transport http novaflow \
  http://<instance-ip>/cell/controlplane/api/v1/mcp
```

**VM/Bare-metal instance**

1. Open your instance (`*.instance.wandelbots.io`).
2. Add the instance access token displayed in NOVA Cloud:

```bash
claude mcp add --scope user --transport http novaflow \
  https://<id>.instance.wandelbots.io/cell/controlplane/api/v1/mcp \
  --header "Authorization: Bearer <ACCESS-TOKEN>"
```

3. Start `claude`.
4. Type `/mcp`.
   → The server `novaflow` is displayed as connected with its authoring tools.

## Connect GitHub Copilot (VS Code)

**NOVA Cloud instance**

1. Create `.vscode/mcp.json` in your workspace or use the command palette with `MCP: Add Server`:
   ```json
   {
     "servers": {
       "novaflow": {
         "type": "http",
         "url": "https://<id>.instance.wandelbots.io/cell/controlplane/api/v1/mcp",
         "headers": { "Authorization": "Bearer <ACCESS-TOKEN>" }
       }
     }
   }
   ```

**VM/Bare-metal instance**

1. Create `.vscode/mcp.json` in your workspace (or use the Command Palette →`MCP: Add Server`):
   ```json
   {
     "servers": {
       "novaflow": {
         "type": "http",
         "url": "http://<instance-ip>/cell/controlplane/api/v1/mcp"
       }
     }
   }
   ```

2) Start the server with `MCP: List Servers` → `novaflow` → `Start`. Confirm the trust prompt upon first start.
3) Switch Copilot Chat to agent mode as MCP tools are only available in agent mode.
4) Verify that the tools are available by opening the `Tools` picker in the chat input.
   → The `novaflow` tools `list_node_types`, `validate_tree`, `save_tree`, and others are displayed.

> **Info:** If no tools are displayed,
>
> 1. Verify that you have successfully switched to agent mode.
> 2. Verify that the server is running with `MCP: List Servers` → `Show Output`.
> 3. For NOVA Cloud instances, verify that a valid token is present in the `headers` field.

## Prompt a flow

A saved flow is displayed in the NOVA Flow editor.

Prompt the assistant to build a flow:

> "Look at which actions and globals this cell has, then build a flow that
> moves the robot through the three stored glue poses in sequence. Validate it
> and save it as glue-demo."

The assistant reads your cell's live action catalog, asks you about relevant decisions, e.g., what happens when a step fails, sequential or parallel, safety
conditions, in plain language, validates the flow, and saves it.

## Custom nodes

A custom node can be used like built-in nodes once deployed.

Prompt the assistant to create a custom node:

> "I need a node that computes a zigzag path from parameters. Build and deploy
> it, then use it in a flow."

Using the `get_node_authoring_guide` tool, the assistant scaffolds the service, deploys it to the NOVA OS instance and verifies it in the catalog.

> **Info:** The assistant will display a failed attempt first because it uses a template      that requires access to the `wandelbotsgmbh` GitHub organization. It then proceeds to a fallback and builds the node by hand, writing directly against the
> public PyPI packages the node depends on at runtime: `wandelbots-novaflow`
> and `novaflow-types`.

## Best practices

- Coordinate with other editors of the same flow in the visual editor to avoid overwriting each other's changes.