> For the complete documentation index, see [llms.txt](https://docs.flowcp.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowcp.ai/getting-started/core-concepts.md). # 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-/`, so you can add a branch for any named Bubble branch. Each branch has its own `server-id` and `/mcp/` endpoint, and any branch — including the defaults — can be deleted. See [Managing branches](/guides/manage-branches.md). ## 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](/guides/offer-prompts.md). ## Documentation Page A documentation page is a markdown page of your product's own docs that the server serves to AI clients at `docs://`, 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](/guides/serve-product-docs.md). ## MCP Server An MCP server is the published endpoint at `/mcp/` 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](#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](/guides/configure-oauth.md) and [Manage branches](/guides/manage-branches.md). ## 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](/reference/tool-risk-levels.md) for details.