FlowCP CLI

The FlowCP CLI (flowcp) lets you manage your hosted MCP servers from the terminal or your IDE: connect apps, import OpenAPI documents, enable tools, publish servers, tail execution logs, configure auth, and sync skills, prompts, and widgets as local files.

Installation

Install from npm (Node.js 18 or newer):

npm install -g flowcp
flowcp --help

From a monorepo checkout (development builds):

pnpm install
pnpm --filter flowcp build
node apps/cli/dist/bin.js --help

You can link a development build onto your PATH with pnpm --filter flowcp link --global.

Logging in

flowcp login

Login uses a browser device-code flow: the CLI prints a code and a dashboard URL (/device). Open the URL, sign in if needed, and approve the request — the CLI receives OAuth tokens scoped to your account and current workspace and stores them in ~/.flowcp/config.json (file mode 0600). No password ever passes through the terminal, and the CLI holds no client secret (it is a public OAuth client secured with PKCE).

• flowcp whoami shows the logged-in user and workspace.

• flowcp workspace list / flowcp workspace switch <id> change the active workspace.

• flowcp logout removes stored credentials.

The CLI talks to https://api.flowcp.ai by default. Point it at a different FlowCP instance (e.g. a local dev stack) with --api-url <url> or the FLOWCP_API_URL environment variable.

Headless auth (CI / GitHub Actions)

The device-code flow needs a browser, so it isn't usable on a CI runner. Instead, create a long-lived API token and pass it via an environment variable:

flowcp token create --name "github-actions"

The full token is shown once — store it as a secret. Then, on any machine without flowcp login, set:

Variable	Purpose
FLOWCP_TOKEN	An API token (flowcp_pat_…). Authenticates every command.
FLOWCP_API_URL	API base URL (optional; defaults to https://api.flowcp.ai).
FLOWCP_WORKSPACE_ID	Workspace id (optional; resolved from the token when omitted).
FLOWCP_CONFIG_DIR	Override the config directory (default ~/.flowcp).

export FLOWCP_TOKEN=flowcp_pat_xxxxxxxx
flowcp whoami
flowcp import run --app app_123

Manage tokens with flowcp token list and flowcp token revoke <id>. Tokens are stored hashed; revoke immediately stops a token from working. Tokens are scoped to the workspace and user that created them. See Use FlowCP in GitHub Actions for a full workflow.

The project file: flowcp.json

Most commands need an app or server id. Instead of passing --app / --server every time, run flowcp sync init --app <appId> --server <serverId> in your project directory to create a flowcp.json:

{
  "appId": "app_...",
  "serverId": "srv_...",
  "workspaceId": "ws_...",
  "sync": {
    "skills": "Skills",
    "prompts": "Prompts",
    "widgets": "Widgets",
    "resources": "Resources",
    "docs": "Docs"
  }
}

The CLI finds the nearest flowcp.json by walking up from the current directory.

Command reference

Command	Description
flowcp login / logout / whoami	Authenticate the CLI
flowcp token create --name <n> / list / revoke <id>	Manage API tokens for headless / CI use
flowcp workspace list / switch <id>	Manage the active workspace
flowcp app list / get [appId] / connect	Manage connected apps
flowcp import run [--app <id>]	Provision servers + import the OpenAPI doc (waits by default; --no-watch to queue only)
flowcp import folder <dir> [--server <id>] [--prune]	Import a standard FlowCP folder's content into a server
flowcp import status <importId> [--watch]	Check or watch an import
flowcp tools list / enable <toolId> / disable <toolId>	Manage generated tools
flowcp server publish / unpublish	Publish or unpublish a server
flowcp server config	Print the MCP connection config (paste into an AI client)
flowcp server test	Run the MCP capability test suite
flowcp export [--server <id>] [--out <dir>]	Export a published server as a self-hostable standard FlowCP folder (paid plans)
flowcp logs [--follow]	Show (or tail) tool execution logs
flowcp invoke "<message>"	Run one playground chat turn against the server's tools
flowcp oauth get / set	Manage the app's user-context OAuth provider config
flowcp auth-config list / set / delete <id>	Manage shared-credential auth (api_key / bearer / none)
flowcp domains list / add <hostname> / get <id> / remove <id>	Manage custom domains
flowcp sync init / pull / push [--prune]	Sync skills, prompts, widgets, resources, and docs as local files

Run flowcp <command> --help for the full option list of any command.

A typical flow

flowcp login
flowcp app connect --name "My API" --provider openapi \
  --swagger-url https://api.example.com/openapi.json \
  --api-base-url https://api.example.com
# verify ownership in the dashboard, then:
flowcp import run --app <appId>
flowcp sync init --app <appId> --server <serverId>
flowcp tools list
flowcp tools enable <toolId>
flowcp server publish
flowcp server config
flowcp logs --follow

Local sync for skills, prompts, widgets, resources, and docs

flowcp sync pull downloads the server's skills, prompts, resources, and documentation pages as Markdown files with a frontmatter block, and widgets as an .html file plus a .json metadata sidecar, into the standard FlowCP folder directories:

Skills/lookup_order.md
Prompts/errors.md
Widgets/order_card.html
Widgets/order_card.json
Resources/catalog.md
Docs/overview.md
Docs/guides/webhooks.md

Docs/ is the one directory that nests: a page's file path below Docs/ is its slug, so Docs/guides/webhooks.md syncs to the page served at docs://guides/webhooks.

Edit them locally (with your IDE and version control), then flowcp sync push to upload changes. New files are created, changed files are updated, and --prune deletes server-side items that no longer have a local file.

Exporting a self-hostable folder

On a paid plan you can export a published server as a portable standard FlowCP folder and run it on your own infrastructure with the FlowCP standalone runtime image — no FlowCP connection, Postgres, or Redis required:

flowcp export --server <serverId> --out ./my-server
cd my-server
cp .env.example .env   # fill in FLOWCP_UPSTREAM_SECRET and any other values
docker compose up

The folder is language-agnostic (config.yaml + per-item files + your OpenAPI document) and never contains secrets — you supply your upstream credential via the environment at run time. To import a folder's content into another server, use flowcp import folder <dir>. See Export & self-host your MCP server.

A skill file looks like:

---
description: 'Look up an order and summarize it'
enabled: true
---

# Lookup order

1. Call `get_order` with the order id...

Scripting with --json

Every command accepts --json and prints the raw API payload, suitable for piping into jq:

flowcp tools list --json | jq -r '.tools[] | select(.enabled) | .name'

Exit codes: 0 success, 1 generic error, 2 usage/validation error, 3 authentication required, 4 not found.