Core concepts

Workspace

A workspace is the top-level container for everything in FlowCP. All apps, servers, OAuth configurations, and end-user connections belong to a single workspace. If you are an agency managing multiple client apps, each client should have its own workspace.

App

An App record in FlowCP represents one connected API. It stores the Swagger/OpenAPI document URL, the API base URL, the provider (which adapter handles it), and the OAuth credentials. You can connect multiple apps inside a single workspace.

The provider determines how FlowCP discovers and talks to the API:

• Generic OpenAPI (openapi) — you paste the Swagger/OpenAPI document URL directly. FlowCP makes no assumptions about path conventions or response envelopes.

• Bubble (bubble) — you enter a Bubble App ID and FlowCP derives the Swagger URL, reads app metadata (custom domain, favicon), and applies Bubble-specific endpoint and pagination handling.

Branch (MCP Server)

Each app has one or more branches, and each branch is its own MCP server with an independent tool set and publish state.

• Generic OpenAPI apps start with a single Default branch pointing at the document you connected.

• Bubble-connected apps create two branches automatically after verification: Live (your live Bubble URL) and Main (the default development branch, served at /version-test/). Bubble development branches live at /version-<id>/, so you can add a branch for any named Bubble branch.

Each branch has its own server-id and /mcp/<server-id> endpoint, and any branch — including the defaults — can be deleted. See Managing branches.

Swagger Import

When you provision an app, FlowCP fetches and parses its Swagger/OpenAPI document for each branch, using that branch's URL. The import job resolves all endpoint definitions and creates a set of MCP tools for that branch's server. Imports are idempotent — re-importing updates existing tools rather than duplicating them.

MCP Tool

An MCP tool is the FlowCP representation of one API endpoint. It stores:

• Name — a human-readable identifier used by AI clients

• Description — passed to the AI as context about what the tool does

• Method and path — the underlying API call

• Input schema — a Zod-validated JSON schema describing expected parameters

• Risk level — read, write, or destructive

• Enabled — whether AI clients can invoke this tool

Tools start disabled and must be explicitly enabled.

MCP Prompt

An MCP prompt is a reusable, parameterized message template a server offers to clients via the MCP prompts/list and prompts/get methods. Unlike tools (which the model calls), prompts are user-controlled — clients surface them to the user, often as slash-commands. A prompt stores a message body with {{argName}} placeholders, a set of declared arguments the user fills in, and optional embedded resources. Like tools, prompts start disabled and must be explicitly enabled. See Offer prompts.

Documentation Page

A documentation page is a markdown page of your product's own docs that the server serves to AI clients at docs://<slug>, alongside two built-in tools: search_docs (find pages by title, description, or heading) and read_doc (return one page's text). With docs connected, an agent answers "how does X work?" from your documentation rather than from guesswork. Pages can be written in the dashboard or committed to a Docs/ directory in a connected repository, and like tools they start disabled. See Serve product documentation.

MCP Server

An MCP server is the published endpoint at /mcp/<server-id> that AI clients connect to. A server represents one branch of an App and exposes that branch's enabled tools. An App can have several servers (one per branch), each published independently. Servers have three statuses:

Status	Meaning
draft	Not yet published. AI clients cannot connect.
published	Live and accepting MCP connections.
disabled	Suspended. Connections are rejected.

OAuth Provider Config

An OAuth provider config stores a named set of OAuth credentials (Client ID and Client Secret) plus the authorize/token URLs. FlowCP uses these to run the OAuth authorization code flow when an end user first connects their AI client. For Bubble apps the authorize/token URLs are derived from the app; for generic providers you enter them directly. The client secret is encrypted at rest. Access tokens are never stored by FlowCP — the AI client holds them and presents them on every request.

An App can have several named configs, and each branch (MCP server) is assigned exactly one. A config can be shared by many branches, but a branch with no config assigned will not authenticate. New branches inherit the app's default (first) config. See Configure OAuth and Manage branches.

Risk Level

Every tool is classified by risk:

• read — Safe GET calls that only retrieve data

• write — POST/PATCH/PUT calls that create or modify data

• destructive — DELETE calls that remove data

See Tool risk levels for details.